pygemstone 0.0.2__tar.gz → 0.0.4__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. {pygemstone-0.0.2/src/pygemstone.egg-info → pygemstone-0.0.4}/PKG-INFO +2 -1
  2. {pygemstone-0.0.2 → pygemstone-0.0.4}/pyproject.toml +6 -1
  3. {pygemstone-0.0.2 → pygemstone-0.0.4}/src/pygemstone/__init__.py +22 -14
  4. {pygemstone-0.0.2 → pygemstone-0.0.4}/src/pygemstone/appsync.py +4 -3
  5. {pygemstone-0.0.2 → pygemstone-0.0.4}/src/pygemstone/auth.py +5 -5
  6. {pygemstone-0.0.2 → pygemstone-0.0.4}/src/pygemstone/client.py +37 -2
  7. pygemstone-0.0.4/src/pygemstone/color.py +96 -0
  8. {pygemstone-0.0.2 → pygemstone-0.0.4}/src/pygemstone/device.py +13 -2
  9. {pygemstone-0.0.2 → pygemstone-0.0.4}/src/pygemstone/models.py +99 -23
  10. {pygemstone-0.0.2 → pygemstone-0.0.4/src/pygemstone.egg-info}/PKG-INFO +2 -1
  11. {pygemstone-0.0.2 → pygemstone-0.0.4}/src/pygemstone.egg-info/SOURCES.txt +2 -0
  12. {pygemstone-0.0.2 → pygemstone-0.0.4}/src/pygemstone.egg-info/requires.txt +1 -0
  13. {pygemstone-0.0.2 → pygemstone-0.0.4}/tests/test_appsync.py +1 -2
  14. {pygemstone-0.0.2 → pygemstone-0.0.4}/tests/test_auth.py +2 -2
  15. {pygemstone-0.0.2 → pygemstone-0.0.4}/tests/test_client.py +66 -1
  16. pygemstone-0.0.4/tests/test_color.py +66 -0
  17. {pygemstone-0.0.2 → pygemstone-0.0.4}/tests/test_models.py +39 -1
  18. {pygemstone-0.0.2 → pygemstone-0.0.4}/LICENSE +0 -0
  19. {pygemstone-0.0.2 → pygemstone-0.0.4}/README.md +0 -0
  20. {pygemstone-0.0.2 → pygemstone-0.0.4}/setup.cfg +0 -0
  21. {pygemstone-0.0.2 → pygemstone-0.0.4}/src/pygemstone/__main__.py +0 -0
  22. {pygemstone-0.0.2 → pygemstone-0.0.4}/src/pygemstone/const.py +0 -0
  23. {pygemstone-0.0.2 → pygemstone-0.0.4}/src/pygemstone/errors.py +0 -0
  24. {pygemstone-0.0.2 → pygemstone-0.0.4}/src/pygemstone/py.typed +0 -0
  25. {pygemstone-0.0.2 → pygemstone-0.0.4}/src/pygemstone.egg-info/dependency_links.txt +0 -0
  26. {pygemstone-0.0.2 → pygemstone-0.0.4}/src/pygemstone.egg-info/entry_points.txt +0 -0
  27. {pygemstone-0.0.2 → pygemstone-0.0.4}/src/pygemstone.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pygemstone
3
- Version: 0.0.2
3
+ Version: 0.0.4
4
4
  Summary: Python library for Gemstone Lights permanent-Christmas-lights controllers (AWS-backed cloud API)
5
5
  Author-email: Stefan Slivinski <sslivins@gmail.com>
6
6
  License: MIT
@@ -18,6 +18,7 @@ Requires-Dist: pycognito>=2024.5.1
18
18
  Provides-Extra: tests
19
19
  Requires-Dist: pytest>=8.3.4; extra == "tests"
20
20
  Requires-Dist: pytest-asyncio>=0.25.3; extra == "tests"
21
+ Requires-Dist: aiohttp<3.14; extra == "tests"
21
22
  Requires-Dist: aioresponses>=0.7.8; extra == "tests"
22
23
  Requires-Dist: python-dotenv>=1.0.1; extra == "tests"
23
24
  Requires-Dist: pytest-cov>=5.0.0; extra == "tests"
@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
6
6
 
7
7
  [project]
8
8
  name = "pygemstone"
9
- version = "0.0.2"
9
+ version = "0.0.4"
10
10
  description = "Python library for Gemstone Lights permanent-Christmas-lights controllers (AWS-backed cloud API)"
11
11
  readme = "README.md"
12
12
  license = { text = "MIT" }
@@ -34,6 +34,11 @@ dependencies = [
34
34
  tests = [
35
35
  "pytest>=8.3.4",
36
36
  "pytest-asyncio>=0.25.3",
37
+ # aioresponses 0.7.8 mocks aiohttp's ClientResponse, which gained a
38
+ # required `stream_writer` kwarg in aiohttp 3.14. Until aioresponses
39
+ # supports 3.14, cap the *test* env to 3.13.x. The runtime dependency
40
+ # above stays open so downstream installs are unaffected.
41
+ "aiohttp<3.14",
37
42
  "aioresponses>=0.7.8",
38
43
  "python-dotenv>=1.0.1",
39
44
  "pytest-cov>=5.0.0",
@@ -3,6 +3,7 @@
3
3
  from .appsync import AppSyncClient
4
4
  from .auth import GemstoneAuth, TokenSet
5
5
  from .client import GemstoneClient
6
+ from .color import color_to_hex, pack_color, unpack_color
6
7
  from .device import Device
7
8
  from .errors import (
8
9
  GemstoneApiError,
@@ -12,10 +13,10 @@ from .errors import (
12
13
  GemstoneNotFoundError,
13
14
  GemstoneValueError,
14
15
  )
15
- from .models import Device as DeviceRecord
16
16
  from .models import (
17
17
  AccountProfile,
18
18
  Announcement,
19
+ ArchitecturalDesign,
19
20
  DeviceState,
20
21
  DownloadableFolder,
21
22
  DownloadablePattern,
@@ -27,27 +28,25 @@ from .models import (
27
28
  HomeGroup,
28
29
  HomeGroupUser,
29
30
  Pattern,
31
+ StaticColorSegment,
30
32
  SubscribedEvent,
31
33
  Swatch,
32
34
  SwatchColor,
33
35
  Timer,
34
36
  TimerData,
35
37
  )
38
+ from .models import Device as DeviceRecord
36
39
 
37
40
  __version__ = "0.0.1"
38
41
 
39
42
  __all__ = [
40
- "GemstoneClient",
41
- "GemstoneAuth",
43
+ "AccountProfile",
44
+ "Announcement",
42
45
  "AppSyncClient",
43
- "TokenSet",
46
+ "ArchitecturalDesign",
44
47
  "Device",
45
48
  "DeviceRecord",
46
49
  "DeviceState",
47
- "HomeGroup",
48
- "Pattern",
49
- "AccountProfile",
50
- "Announcement",
51
50
  "DownloadableFolder",
52
51
  "DownloadablePattern",
53
52
  "EventCategory",
@@ -55,17 +54,26 @@ __all__ = [
55
54
  "EventsSettings",
56
55
  "Folder",
57
56
  "FolderPattern",
57
+ "GemstoneApiError",
58
+ "GemstoneAuth",
59
+ "GemstoneAuthError",
60
+ "GemstoneClient",
61
+ "GemstoneConnectionError",
62
+ "GemstoneError",
63
+ "GemstoneNotFoundError",
64
+ "GemstoneValueError",
65
+ "HomeGroup",
58
66
  "HomeGroupUser",
67
+ "Pattern",
68
+ "StaticColorSegment",
59
69
  "SubscribedEvent",
60
70
  "Swatch",
61
71
  "SwatchColor",
62
72
  "Timer",
63
73
  "TimerData",
64
- "GemstoneError",
65
- "GemstoneAuthError",
66
- "GemstoneApiError",
67
- "GemstoneConnectionError",
68
- "GemstoneNotFoundError",
69
- "GemstoneValueError",
74
+ "TokenSet",
70
75
  "__version__",
76
+ "color_to_hex",
77
+ "pack_color",
78
+ "unpack_color",
71
79
  ]
@@ -52,8 +52,9 @@ import base64
52
52
  import json
53
53
  import logging
54
54
  import uuid
55
+ from collections.abc import AsyncIterator
55
56
  from contextlib import asynccontextmanager
56
- from typing import Any, AsyncIterator
57
+ from typing import Any
57
58
  from urllib.parse import urlparse
58
59
 
59
60
  import aiohttp
@@ -296,8 +297,8 @@ class AppSyncClient:
296
297
  if not ws.closed:
297
298
  try:
298
299
  await ws.send_json({"id": sub_id, "type": "stop"})
299
- except Exception: # noqa: BLE001 - best-effort cleanup
300
- pass
300
+ except Exception:
301
+ logger.debug("Failed to send WS unsubscribe", exc_info=True)
301
302
  except aiohttp.ClientError as exc:
302
303
  raise GemstoneConnectionError(
303
304
  f"AppSync WS connect failed: {exc}"
@@ -18,7 +18,7 @@ import time
18
18
  from dataclasses import dataclass
19
19
  from typing import Any
20
20
 
21
- from .const import COGNITO_CLIENT_ID, COGNITO_USER_POOL_ID, AWS_REGION
21
+ from .const import AWS_REGION, COGNITO_CLIENT_ID, COGNITO_USER_POOL_ID
22
22
  from .errors import GemstoneAuthError
23
23
 
24
24
  logger = logging.getLogger(__name__)
@@ -129,7 +129,7 @@ class GemstoneAuth:
129
129
  username=self._email,
130
130
  )
131
131
  cog.authenticate(password=self._password)
132
- except Exception as exc: # noqa: BLE001 — pycognito raises various
132
+ except Exception as exc:
133
133
  raise GemstoneAuthError(f"Cognito SRP auth failed: {exc}") from exc
134
134
 
135
135
  return self._tokens_from_cognito(cog)
@@ -153,7 +153,7 @@ class GemstoneAuth:
153
153
  # refresh_token via REFRESH_TOKEN_AUTH and replaces access/id
154
154
  # tokens on the Cognito instance.
155
155
  cog.renew_access_token()
156
- except Exception as exc: # noqa: BLE001
156
+ except Exception as exc:
157
157
  raise GemstoneAuthError(f"Token refresh failed: {exc}") from exc
158
158
 
159
159
  return self._tokens_from_cognito(cog, refresh_fallback=refresh_token)
@@ -170,9 +170,9 @@ class GemstoneAuth:
170
170
  client = boto3.client("cognito-idp", region_name=self._region)
171
171
  try:
172
172
  client.global_sign_out(AccessToken=access_token)
173
- except Exception: # noqa: BLE001
173
+ except Exception:
174
174
  # 401 here means the token already expired — fine to ignore.
175
- pass
175
+ logger.debug("Global sign-out failed (token likely expired)", exc_info=True)
176
176
 
177
177
  @staticmethod
178
178
  def _tokens_from_cognito(
@@ -8,9 +8,10 @@ capture (:mod:`pygemstone.const`).
8
8
  from __future__ import annotations
9
9
 
10
10
  import logging
11
+ from collections.abc import AsyncIterator
11
12
  from contextlib import asynccontextmanager
12
13
  from types import TracebackType
13
- from typing import Any, AsyncIterator, Self
14
+ from typing import Any, Self
14
15
 
15
16
  import aiohttp
16
17
 
@@ -26,6 +27,7 @@ from .errors import (
26
27
  from .models import (
27
28
  AccountProfile,
28
29
  Announcement,
30
+ ArchitecturalDesign,
29
31
  DeviceState,
30
32
  DownloadableFolder,
31
33
  DownloadablePattern,
@@ -295,6 +297,39 @@ class GemstoneClient:
295
297
  DownloadablePattern.from_api(p) for p in payload.get("data", []) or []
296
298
  ]
297
299
 
300
+ # ------------------------------------------------------------------
301
+ # Architectural designs ("Custom Designs" / "Quick Access")
302
+ # ------------------------------------------------------------------
303
+
304
+ async def architectural_designs(self, device_id: str) -> list[ArchitecturalDesign]:
305
+ """List a single device's saved "Custom Designs" (Quick Access).
306
+
307
+ Unlike folder patterns these are per-device, not per-homegroup —
308
+ discovered via a live capture since they're not returned by
309
+ ``/folders/list`` or ``/folders/pattern/list``.
310
+ """
311
+ payload = await self._get(
312
+ "/deviceControl/architectural/list", params={"deviceId": device_id}
313
+ )
314
+ return [
315
+ ArchitecturalDesign.from_api(d) for d in payload.get("data", []) or []
316
+ ]
317
+
318
+ async def save_architectural_design(
319
+ self, design: ArchitecturalDesign
320
+ ) -> ArchitecturalDesign:
321
+ """Create or update (and immediately apply) a device's custom design.
322
+
323
+ Pass a design with a blank ``id`` to create a new one, or an
324
+ existing ``id`` to update + apply it in place.
325
+ """
326
+ payload = await self._put(
327
+ "/deviceControl/architectural/save",
328
+ params={"deviceId": design.device_id},
329
+ json_body=design.to_api(),
330
+ )
331
+ return ArchitecturalDesign.from_api(payload.get("data", {}) or {})
332
+
298
333
  # ------------------------------------------------------------------
299
334
  # Autopilot / scheduling
300
335
  # ------------------------------------------------------------------
@@ -409,7 +444,7 @@ class GemstoneClient:
409
444
  return {}
410
445
  try:
411
446
  data: dict[str, Any] = await resp.json(content_type=None)
412
- except Exception as exc: # noqa: BLE001
447
+ except Exception as exc:
413
448
  raise GemstoneApiError(
414
449
  resp.status, text, message=f"Invalid JSON: {exc}"
415
450
  ) from exc
@@ -0,0 +1,96 @@
1
+ """Colour packing helpers for the Gemstone API.
2
+
3
+ Gemstone stores every colour as a single 32-bit integer using a
4
+ **little-endian, red-in-the-low-byte** layout::
5
+
6
+ bits 0- 7 → R (red)
7
+ bits 8-15 → G (green)
8
+ bits 16-23 → B (blue)
9
+ bits 24-31 → W (dedicated white LED channel on RGBW strips)
10
+
11
+ So ``0x00000000WWBBGGRR``. This is *not* the conventional ``0xRRGGBB`` /
12
+ ARGB ordering, which is an easy and costly mistake to make — pure red
13
+ ``(255, 0, 0)`` is stored as the integer ``255`` (``0x000000FF``), which
14
+ naively read as ``0xRRGGBB`` decodes to blue.
15
+
16
+ Reference values straight from the cloud's own swatch data:
17
+
18
+ 255 → "Red" (0x000000FF)
19
+ 65280 → "Green" (0x0000FF00)
20
+ 16711680 → blue (0x00FF0000)
21
+ 16777215 → "Cool White" (0x00FFFFFF)
22
+ 4278190080 → "Warm White" (0xFF000000 — white channel only, no RGB)
23
+
24
+ The :class:`~pygemstone.models.Pattern` / :class:`~pygemstone.models.SwatchColor`
25
+ models keep these as raw ints (so they can be replayed to the API
26
+ unchanged). Use the helpers here whenever you need to *interpret* or
27
+ *construct* a colour rather than echo one back verbatim.
28
+ """
29
+
30
+ from __future__ import annotations
31
+
32
+ from typing import Any
33
+
34
+ __all__ = ["color_to_hex", "pack_color", "unpack_color"]
35
+
36
+
37
+ def unpack_color(value: Any) -> tuple[int, int, int, int]:
38
+ """Split a packed Gemstone colour int into ``(r, g, b, w)`` byte values.
39
+
40
+ ``w`` is the dedicated white-LED channel (top byte). Each component is
41
+ an ``int`` in the range ``0``–``255``.
42
+
43
+ >>> unpack_color(255)
44
+ (255, 0, 0, 0)
45
+ >>> unpack_color(65280)
46
+ (0, 255, 0, 0)
47
+ >>> unpack_color(4278190080)
48
+ (0, 0, 0, 255)
49
+
50
+ :raises GemstoneValueError: if ``value`` is not an integer.
51
+ """
52
+ try:
53
+ n = int(value)
54
+ except (TypeError, ValueError) as exc:
55
+ from .errors import GemstoneValueError
56
+
57
+ raise GemstoneValueError(f"not a packed colour int: {value!r}") from exc
58
+ return (n & 0xFF, (n >> 8) & 0xFF, (n >> 16) & 0xFF, (n >> 24) & 0xFF)
59
+
60
+
61
+ def pack_color(r: int, g: int, b: int, w: int = 0) -> int:
62
+ """Pack ``(r, g, b, w)`` byte components into a Gemstone colour int.
63
+
64
+ Inverse of :func:`unpack_color`. Each component is masked to 0–255.
65
+
66
+ >>> pack_color(255, 0, 0)
67
+ 255
68
+ >>> pack_color(0, 255, 0)
69
+ 65280
70
+ >>> pack_color(0, 0, 0, 255)
71
+ 4278190080
72
+ """
73
+ return (
74
+ (int(r) & 0xFF)
75
+ | ((int(g) & 0xFF) << 8)
76
+ | ((int(b) & 0xFF) << 16)
77
+ | ((int(w) & 0xFF) << 24)
78
+ )
79
+
80
+
81
+ def color_to_hex(value: Any) -> str:
82
+ """Convert a packed Gemstone colour int to a CSS ``#rrggbb`` string.
83
+
84
+ The white channel is dropped — only the RGB triplet is represented.
85
+ Callers that care about the white channel (e.g. to show a warm-white
86
+ swatch) should use :func:`unpack_color` directly.
87
+
88
+ >>> color_to_hex(255)
89
+ '#ff0000'
90
+ >>> color_to_hex(16777215)
91
+ '#ffffff'
92
+
93
+ :raises GemstoneValueError: if ``value`` is not an integer.
94
+ """
95
+ r, g, b, _ = unpack_color(value)
96
+ return f"#{r:02x}{g:02x}{b:02x}"
@@ -10,7 +10,8 @@ from __future__ import annotations
10
10
 
11
11
  from typing import TYPE_CHECKING, Any
12
12
 
13
- from .models import Device as DeviceRecord, DeviceState, Pattern
13
+ from .models import ArchitecturalDesign, DeviceState, Pattern
14
+ from .models import Device as DeviceRecord
14
15
 
15
16
  if TYPE_CHECKING:
16
17
  from .client import GemstoneClient
@@ -19,7 +20,7 @@ if TYPE_CHECKING:
19
20
  class Device:
20
21
  """A Gemstone controller bound to a live client."""
21
22
 
22
- def __init__(self, client: "GemstoneClient", payload: dict[str, Any]) -> None:
23
+ def __init__(self, client: GemstoneClient, payload: dict[str, Any]) -> None:
23
24
  self._client = client
24
25
  self._record = DeviceRecord.from_api(payload)
25
26
  self._state: DeviceState | None = None
@@ -62,5 +63,15 @@ class Device:
62
63
  async def play_pattern(self, pattern: Pattern) -> str:
63
64
  return await self._client.play_pattern(self.id, pattern)
64
65
 
66
+ async def architectural_designs(self) -> list[ArchitecturalDesign]:
67
+ """This device's saved "Custom Designs" (Quick Access)."""
68
+ return await self._client.architectural_designs(self.id)
69
+
70
+ async def apply_architectural_design(
71
+ self, design: ArchitecturalDesign
72
+ ) -> ArchitecturalDesign:
73
+ """Re-save (and thereby apply) one of this device's custom designs."""
74
+ return await self._client.save_architectural_design(design)
75
+
65
76
  def __repr__(self) -> str:
66
77
  return f"<Device id={self.id!r} name={self.name!r}>"
@@ -1,14 +1,19 @@
1
1
  """Typed dataclasses for the Gemstone API response surface.
2
2
 
3
3
  These mirror the JSON shapes returned by the cloud, with a small
4
- amount of normalisation (timestamps → ``datetime``, ARGB ints → kept
5
- as raw ints since they're convenient to push back unchanged).
4
+ amount of normalisation (timestamps → ``datetime``, colours kept as
5
+ raw packed ints since they're convenient to push back unchanged).
6
+
7
+ Colours use Gemstone's little-endian, red-in-the-low-byte layout
8
+ (``0xWWBBGGRR``) — see :mod:`pygemstone.color` for ``unpack_color`` /
9
+ ``pack_color`` / ``color_to_hex`` helpers rather than decoding the
10
+ ints by hand.
6
11
  """
7
12
 
8
13
  from __future__ import annotations
9
14
 
10
15
  from dataclasses import dataclass, field
11
- from datetime import datetime, timezone
16
+ from datetime import UTC, datetime
12
17
  from typing import Any
13
18
 
14
19
 
@@ -17,7 +22,7 @@ def _ts(value: Any) -> datetime | None:
17
22
  if value is None:
18
23
  return None
19
24
  try:
20
- return datetime.fromtimestamp(int(value), tz=timezone.utc)
25
+ return datetime.fromtimestamp(int(value), tz=UTC)
21
26
  except (TypeError, ValueError):
22
27
  return None
23
28
 
@@ -34,7 +39,7 @@ class HomeGroup:
34
39
  created_at: datetime | None = None
35
40
 
36
41
  @classmethod
37
- def from_api(cls, payload: dict[str, Any]) -> "HomeGroup":
42
+ def from_api(cls, payload: dict[str, Any]) -> HomeGroup:
38
43
  return cls(
39
44
  id=payload["id"],
40
45
  name=payload.get("name", ""),
@@ -58,7 +63,7 @@ class Device:
58
63
  raw: dict[str, Any] = field(default_factory=dict)
59
64
 
60
65
  @classmethod
61
- def from_api(cls, payload: dict[str, Any]) -> "Device":
66
+ def from_api(cls, payload: dict[str, Any]) -> Device:
62
67
  return cls(
63
68
  id=payload["id"],
64
69
  name=payload.get("name", ""),
@@ -91,7 +96,7 @@ class Pattern:
91
96
  raw: dict[str, Any] = field(default_factory=dict)
92
97
 
93
98
  @classmethod
94
- def from_api(cls, payload: dict[str, Any]) -> "Pattern":
99
+ def from_api(cls, payload: dict[str, Any]) -> Pattern:
95
100
  return cls(
96
101
  id=payload["id"],
97
102
  name=payload.get("name", ""),
@@ -133,7 +138,7 @@ class DeviceState:
133
138
  raw: dict[str, Any] = field(default_factory=dict)
134
139
 
135
140
  @classmethod
136
- def from_api(cls, payload: dict[str, Any]) -> "DeviceState":
141
+ def from_api(cls, payload: dict[str, Any]) -> DeviceState:
137
142
  pat = payload.get("pattern")
138
143
  return cls(
139
144
  device_id=payload["id"],
@@ -159,7 +164,7 @@ class AccountProfile:
159
164
  raw: dict[str, Any] = field(default_factory=dict)
160
165
 
161
166
  @classmethod
162
- def from_api(cls, payload: dict[str, Any]) -> "AccountProfile":
167
+ def from_api(cls, payload: dict[str, Any]) -> AccountProfile:
163
168
  return cls(
164
169
  id=payload.get("id", ""),
165
170
  username=payload.get("username", ""),
@@ -189,7 +194,7 @@ class HomeGroupUser:
189
194
  raw: dict[str, Any] = field(default_factory=dict)
190
195
 
191
196
  @classmethod
192
- def from_api(cls, payload: dict[str, Any]) -> "HomeGroupUser":
197
+ def from_api(cls, payload: dict[str, Any]) -> HomeGroupUser:
193
198
  return cls(
194
199
  user_id=payload.get("userId", ""),
195
200
  homegroup_id=payload.get("homegroupId", ""),
@@ -225,7 +230,7 @@ class Folder:
225
230
  raw: dict[str, Any] = field(default_factory=dict)
226
231
 
227
232
  @classmethod
228
- def from_api(cls, payload: dict[str, Any]) -> "Folder":
233
+ def from_api(cls, payload: dict[str, Any]) -> Folder:
229
234
  bg = payload.get("backgroundColor")
230
235
  return cls(
231
236
  folder_id=payload.get("folderId", ""),
@@ -265,7 +270,7 @@ class FolderPattern:
265
270
  raw: dict[str, Any] = field(default_factory=dict)
266
271
 
267
272
  @classmethod
268
- def from_api(cls, payload: dict[str, Any]) -> "FolderPattern":
273
+ def from_api(cls, payload: dict[str, Any]) -> FolderPattern:
269
274
  pat_data = payload.get("patternData", {}) or {}
270
275
  return cls(
271
276
  id=payload.get("id", ""),
@@ -283,6 +288,77 @@ class FolderPattern:
283
288
  )
284
289
 
285
290
 
291
+ @dataclass(slots=True)
292
+ class StaticColorSegment:
293
+ """One coloured light segment within an :class:`ArchitecturalDesign`.
294
+
295
+ ``lights`` is the raw per-segment light-index/count payload sent by
296
+ the app; we don't yet know its exact semantics so it's kept as-is.
297
+ """
298
+
299
+ lights: list[int] = field(default_factory=list)
300
+ color: int = 0
301
+
302
+ @classmethod
303
+ def from_api(cls, payload: dict[str, Any]) -> StaticColorSegment:
304
+ return cls(
305
+ lights=list(payload.get("lights", []) or []),
306
+ color=int(payload.get("color", 0)),
307
+ )
308
+
309
+ def to_api(self) -> dict[str, Any]:
310
+ return {"lights": self.lights, "color": self.color}
311
+
312
+
313
+ @dataclass(slots=True)
314
+ class ArchitecturalDesign:
315
+ """A saved "Quick Access" / "Custom Design" look for one device.
316
+
317
+ Unlike folder patterns, these are stored per-device (``deviceId``)
318
+ rather than per-homegroup, via ``/deviceControl/architectural/list``
319
+ and ``/deviceControl/architectural/save``. Re-``save``-ing a design
320
+ with its existing ``id`` both updates and immediately applies it.
321
+ """
322
+
323
+ id: str
324
+ device_id: str
325
+ name: str
326
+ brightness: int = 255
327
+ static_colors: list[StaticColorSegment] = field(default_factory=list)
328
+ is_favorite: bool = False
329
+ created_at: datetime | None = None
330
+ last_updated_at: datetime | None = None
331
+ raw: dict[str, Any] = field(default_factory=dict)
332
+
333
+ @classmethod
334
+ def from_api(cls, payload: dict[str, Any]) -> ArchitecturalDesign:
335
+ return cls(
336
+ id=payload.get("id", ""),
337
+ device_id=payload.get("deviceId", ""),
338
+ name=payload.get("name", ""),
339
+ brightness=int(payload.get("brightness", 255)),
340
+ static_colors=[
341
+ StaticColorSegment.from_api(sc)
342
+ for sc in payload.get("staticColors", []) or []
343
+ ],
344
+ is_favorite=bool(payload.get("isFavorite", False)),
345
+ created_at=_ts(payload.get("createdAt")),
346
+ last_updated_at=_ts(payload.get("lastUpdatedAt")),
347
+ raw=payload,
348
+ )
349
+
350
+ def to_api(self) -> dict[str, Any]:
351
+ """Render back to the wire format expected by ``architectural/save``."""
352
+ return {
353
+ "id": self.id,
354
+ "deviceId": self.device_id,
355
+ "name": self.name,
356
+ "brightness": self.brightness,
357
+ "staticColors": [sc.to_api() for sc in self.static_colors],
358
+ "isFavorite": self.is_favorite,
359
+ }
360
+
361
+
286
362
  @dataclass(slots=True)
287
363
  class DownloadableFolder:
288
364
  """A Gemstone-curated folder available for download.
@@ -305,7 +381,7 @@ class DownloadableFolder:
305
381
  raw: dict[str, Any] = field(default_factory=dict)
306
382
 
307
383
  @classmethod
308
- def from_api(cls, payload: dict[str, Any]) -> "DownloadableFolder":
384
+ def from_api(cls, payload: dict[str, Any]) -> DownloadableFolder:
309
385
  bg = payload.get("backgroundColor")
310
386
  return cls(
311
387
  id=payload.get("id", ""),
@@ -345,7 +421,7 @@ class DownloadablePattern:
345
421
  raw: dict[str, Any] = field(default_factory=dict)
346
422
 
347
423
  @classmethod
348
- def from_api(cls, payload: dict[str, Any]) -> "DownloadablePattern":
424
+ def from_api(cls, payload: dict[str, Any]) -> DownloadablePattern:
349
425
  pat_data = payload.get("patternData", {}) or {}
350
426
  return cls(
351
427
  id=payload.get("id", ""),
@@ -371,7 +447,7 @@ class SwatchColor:
371
447
  name: str
372
448
 
373
449
  @classmethod
374
- def from_api(cls, payload: dict[str, Any]) -> "SwatchColor":
450
+ def from_api(cls, payload: dict[str, Any]) -> SwatchColor:
375
451
  return cls(color=int(payload.get("color", 0)), name=payload.get("name", ""))
376
452
 
377
453
 
@@ -388,7 +464,7 @@ class Swatch:
388
464
  raw: dict[str, Any] = field(default_factory=dict)
389
465
 
390
466
  @classmethod
391
- def from_api(cls, payload: dict[str, Any]) -> "Swatch":
467
+ def from_api(cls, payload: dict[str, Any]) -> Swatch:
392
468
  return cls(
393
469
  id=payload.get("id", ""),
394
470
  name=payload.get("name", ""),
@@ -413,7 +489,7 @@ class EventsScheduleWindow:
413
489
  off_offset_minutes: int = 0
414
490
 
415
491
  @classmethod
416
- def from_api(cls, payload: dict[str, Any]) -> "EventsScheduleWindow":
492
+ def from_api(cls, payload: dict[str, Any]) -> EventsScheduleWindow:
417
493
  return cls(
418
494
  on_time=payload.get("onTime", ""),
419
495
  off_time=payload.get("offTime", ""),
@@ -438,7 +514,7 @@ class EventsSettings:
438
514
  raw: dict[str, Any] = field(default_factory=dict)
439
515
 
440
516
  @classmethod
441
- def from_api(cls, payload: dict[str, Any]) -> "EventsSettings":
517
+ def from_api(cls, payload: dict[str, Any]) -> EventsSettings:
442
518
  sched = payload.get("schedule")
443
519
  return cls(
444
520
  homegroup_id=payload.get("homegroupId", ""),
@@ -482,7 +558,7 @@ class SubscribedEvent:
482
558
  raw: dict[str, Any] = field(default_factory=dict)
483
559
 
484
560
  @classmethod
485
- def from_api(cls, payload: dict[str, Any]) -> "SubscribedEvent":
561
+ def from_api(cls, payload: dict[str, Any]) -> SubscribedEvent:
486
562
  bg = payload.get("backgroundColor")
487
563
  sel = payload.get("selectedPattern")
488
564
  return cls(
@@ -519,7 +595,7 @@ class TimerData:
519
595
  off_time: str
520
596
 
521
597
  @classmethod
522
- def from_api(cls, payload: dict[str, Any]) -> "TimerData":
598
+ def from_api(cls, payload: dict[str, Any]) -> TimerData:
523
599
  return cls(
524
600
  timer_type=payload.get("timerType", ""),
525
601
  on_time=payload.get("onTime", ""),
@@ -549,7 +625,7 @@ class Timer:
549
625
  raw: dict[str, Any] = field(default_factory=dict)
550
626
 
551
627
  @classmethod
552
- def from_api(cls, payload: dict[str, Any]) -> "Timer":
628
+ def from_api(cls, payload: dict[str, Any]) -> Timer:
553
629
  td = payload.get("timerData")
554
630
  tpd = (payload.get("timerPatternData") or {}).get("pattern")
555
631
  return cls(
@@ -586,7 +662,7 @@ class EventCategory:
586
662
  raw: dict[str, Any] = field(default_factory=dict)
587
663
 
588
664
  @classmethod
589
- def from_api(cls, payload: dict[str, Any]) -> "EventCategory":
665
+ def from_api(cls, payload: dict[str, Any]) -> EventCategory:
590
666
  bg = payload.get("backgroundColor")
591
667
  return cls(
592
668
  id=payload.get("id", ""),
@@ -624,7 +700,7 @@ class Announcement:
624
700
  raw: dict[str, Any] = field(default_factory=dict)
625
701
 
626
702
  @classmethod
627
- def from_api(cls, payload: dict[str, Any]) -> "Announcement":
703
+ def from_api(cls, payload: dict[str, Any]) -> Announcement:
628
704
  bg = payload.get("backgroundColor")
629
705
  return cls(
630
706
  id=payload.get("id", ""),
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pygemstone
3
- Version: 0.0.2
3
+ Version: 0.0.4
4
4
  Summary: Python library for Gemstone Lights permanent-Christmas-lights controllers (AWS-backed cloud API)
5
5
  Author-email: Stefan Slivinski <sslivins@gmail.com>
6
6
  License: MIT
@@ -18,6 +18,7 @@ Requires-Dist: pycognito>=2024.5.1
18
18
  Provides-Extra: tests
19
19
  Requires-Dist: pytest>=8.3.4; extra == "tests"
20
20
  Requires-Dist: pytest-asyncio>=0.25.3; extra == "tests"
21
+ Requires-Dist: aiohttp<3.14; extra == "tests"
21
22
  Requires-Dist: aioresponses>=0.7.8; extra == "tests"
22
23
  Requires-Dist: python-dotenv>=1.0.1; extra == "tests"
23
24
  Requires-Dist: pytest-cov>=5.0.0; extra == "tests"
@@ -6,6 +6,7 @@ src/pygemstone/__main__.py
6
6
  src/pygemstone/appsync.py
7
7
  src/pygemstone/auth.py
8
8
  src/pygemstone/client.py
9
+ src/pygemstone/color.py
9
10
  src/pygemstone/const.py
10
11
  src/pygemstone/device.py
11
12
  src/pygemstone/errors.py
@@ -20,4 +21,5 @@ src/pygemstone.egg-info/top_level.txt
20
21
  tests/test_appsync.py
21
22
  tests/test_auth.py
22
23
  tests/test_client.py
24
+ tests/test_color.py
23
25
  tests/test_models.py
@@ -4,6 +4,7 @@ pycognito>=2024.5.1
4
4
  [tests]
5
5
  pytest>=8.3.4
6
6
  pytest-asyncio>=0.25.3
7
+ aiohttp<3.14
7
8
  aioresponses>=0.7.8
8
9
  python-dotenv>=1.0.1
9
10
  pytest-cov>=5.0.0
@@ -24,7 +24,6 @@ from pygemstone.client import GemstoneClient
24
24
  from pygemstone.const import APPSYNC_API_URL
25
25
  from pygemstone.errors import GemstoneApiError
26
26
 
27
-
28
27
  # ---------------------------------------------------------------------------
29
28
  # WS handshake helpers (pure unit tests)
30
29
  # ---------------------------------------------------------------------------
@@ -58,7 +57,7 @@ class FakeWS:
58
57
  raise RuntimeError("FakeWS inbox exhausted")
59
58
  return self._inbox.pop(0)
60
59
 
61
- def __aiter__(self) -> "FakeWS":
60
+ def __aiter__(self) -> FakeWS:
62
61
  return self
63
62
 
64
63
  async def __anext__(self) -> _FakeMsg:
@@ -8,7 +8,7 @@ methods are called in the right order, and that the resulting
8
8
  from __future__ import annotations
9
9
 
10
10
  import time
11
- from datetime import datetime, timedelta, timezone
11
+ from datetime import UTC, datetime, timedelta
12
12
  from unittest.mock import MagicMock
13
13
 
14
14
  import pytest
@@ -29,7 +29,7 @@ def _fake_cog(
29
29
  cog.access_token = access_token
30
30
  cog.id_token = id_token
31
31
  cog.refresh_token = refresh_token
32
- cog.access_token_expiration = datetime.now(timezone.utc) + timedelta(
32
+ cog.access_token_expiration = datetime.now(UTC) + timedelta(
33
33
  seconds=expires_in
34
34
  )
35
35
  cog.token_expires_in = expires_in
@@ -11,7 +11,7 @@ from pygemstone.auth import TokenSet
11
11
  from pygemstone.client import GemstoneClient
12
12
  from pygemstone.const import REST_API_BASE
13
13
  from pygemstone.errors import GemstoneApiError, GemstoneAuthError
14
- from pygemstone.models import Pattern
14
+ from pygemstone.models import ArchitecturalDesign, Pattern, StaticColorSegment
15
15
 
16
16
 
17
17
  @pytest.fixture
@@ -398,6 +398,71 @@ async def test_downloadable_patterns(gc: GemstoneClient) -> None:
398
398
  assert patterns[0].pattern.animation == "chase"
399
399
 
400
400
 
401
+ @pytest.mark.rest
402
+ async def test_architectural_designs(gc: GemstoneClient) -> None:
403
+ with aioresponses() as m:
404
+ m.get(
405
+ f"{REST_API_BASE}/deviceControl/architectural/list?deviceId=h2-test",
406
+ payload={
407
+ "data": [
408
+ {
409
+ "id": "ad-1",
410
+ "deviceId": "h2-test",
411
+ "name": "Front Door",
412
+ "brightness": 255,
413
+ "staticColors": [
414
+ {"lights": [300, 300, 307], "color": 4294967295}
415
+ ],
416
+ "isFavorite": False,
417
+ "createdAt": 1700000000,
418
+ "lastUpdatedAt": 1700000001,
419
+ }
420
+ ],
421
+ "statusCode": 200,
422
+ },
423
+ )
424
+ designs = await gc.architectural_designs("h2-test")
425
+ assert len(designs) == 1
426
+ assert designs[0].id == "ad-1"
427
+ assert designs[0].name == "Front Door"
428
+ assert designs[0].static_colors[0].color == 4294967295
429
+
430
+
431
+ @pytest.mark.rest
432
+ async def test_save_architectural_design(gc: GemstoneClient) -> None:
433
+ design = ArchitecturalDesign(
434
+ id="ad-1",
435
+ device_id="h2-test",
436
+ name="Front Door",
437
+ brightness=255,
438
+ static_colors=[StaticColorSegment(lights=[300, 300, 307], color=4294967295)],
439
+ is_favorite=False,
440
+ )
441
+ with aioresponses() as m:
442
+ m.put(
443
+ f"{REST_API_BASE}/deviceControl/architectural/save?deviceId=h2-test",
444
+ payload={
445
+ "data": {
446
+ "id": "ad-1",
447
+ "deviceId": "h2-test",
448
+ "name": "Front Door",
449
+ "brightness": 255,
450
+ "staticColors": [
451
+ {"lights": [300, 300, 307], "color": 4294967295}
452
+ ],
453
+ "isFavorite": False,
454
+ "createdAt": 1700000005,
455
+ "lastUpdatedAt": 1700000005,
456
+ },
457
+ "statusCode": 200,
458
+ },
459
+ )
460
+ saved = await gc.save_architectural_design(design)
461
+ assert saved.id == "ad-1"
462
+ req = next(iter(m.requests.values()))[0]
463
+ assert req.kwargs["json"]["name"] == "Front Door"
464
+
465
+
401
466
  @pytest.mark.rest
402
467
  async def test_events_settings(gc: GemstoneClient) -> None:
403
468
  with aioresponses() as m:
@@ -0,0 +1,66 @@
1
+ """Tests for the colour packing helpers.
2
+
3
+ Ground-truth values are the named swatch colours the Gemstone cloud
4
+ itself returns (see test_models.py fixtures): 255 == "Red", etc.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import pytest
10
+
11
+ from pygemstone import color_to_hex, pack_color, unpack_color
12
+ from pygemstone.errors import GemstoneValueError
13
+
14
+
15
+ @pytest.mark.parametrize(
16
+ "packed,rgbw",
17
+ [
18
+ (255, (255, 0, 0, 0)), # "Red"
19
+ (65280, (0, 255, 0, 0)), # "Green"
20
+ (16711680, (0, 0, 255, 0)), # blue
21
+ (16777215, (255, 255, 255, 0)), # "Cool White"
22
+ (4278190080, (0, 0, 0, 255)), # "Warm White" — white channel only
23
+ (4294967295, (255, 255, 255, 255)),
24
+ ],
25
+ )
26
+ def test_unpack_color(packed, rgbw):
27
+ assert unpack_color(packed) == rgbw
28
+
29
+
30
+ @pytest.mark.parametrize(
31
+ "rgbw,packed",
32
+ [
33
+ ((255, 0, 0, 0), 255),
34
+ ((0, 255, 0, 0), 65280),
35
+ ((0, 0, 255, 0), 16711680),
36
+ ((255, 255, 255, 0), 16777215),
37
+ ((0, 0, 0, 255), 4278190080),
38
+ ],
39
+ )
40
+ def test_pack_color(rgbw, packed):
41
+ assert pack_color(*rgbw) == packed
42
+
43
+
44
+ def test_pack_unpack_round_trip():
45
+ for value in (0, 255, 65280, 16711680, 16777215, 4278190080, 4294967295):
46
+ assert pack_color(*unpack_color(value)) == value
47
+
48
+
49
+ def test_pack_color_masks_out_of_range():
50
+ assert pack_color(256, -1, 0) == pack_color(0, 255, 0)
51
+
52
+
53
+ def test_color_to_hex():
54
+ assert color_to_hex(255) == "#ff0000"
55
+ assert color_to_hex(65280) == "#00ff00"
56
+ assert color_to_hex(16711680) == "#0000ff"
57
+ assert color_to_hex(16777215) == "#ffffff"
58
+ # White channel is dropped — warm white has no RGB.
59
+ assert color_to_hex(4278190080) == "#000000"
60
+
61
+
62
+ def test_invalid_input_raises():
63
+ with pytest.raises(GemstoneValueError):
64
+ unpack_color("nope")
65
+ with pytest.raises(GemstoneValueError):
66
+ color_to_hex(None)
@@ -7,6 +7,7 @@ import pytest
7
7
  from pygemstone.models import (
8
8
  AccountProfile,
9
9
  Announcement,
10
+ ArchitecturalDesign,
10
11
  Device,
11
12
  DeviceState,
12
13
  DownloadableFolder,
@@ -23,7 +24,6 @@ from pygemstone.models import (
23
24
  Timer,
24
25
  )
25
26
 
26
-
27
27
  # Sample taken from GET /prod/homegroup/list, sensitive IDs scrubbed.
28
28
  HOMEGROUP_SAMPLE = {
29
29
  "role": "homegroupOwner",
@@ -425,6 +425,44 @@ def test_folder_pattern_decode() -> None:
425
425
  assert fp.pattern.speed == 224
426
426
 
427
427
 
428
+ # Sample taken from GET /prod/deviceControl/architectural/list, IDs scrubbed.
429
+ ARCHITECTURAL_DESIGN_SAMPLE = {
430
+ "staticColors": [
431
+ {"lights": [300, 300, 307], "color": 4294967295},
432
+ ],
433
+ "deviceId": "h2-1074-y3w9",
434
+ "brightness": 255,
435
+ "createdAt": 1787282131,
436
+ "lastUpdatedAt": 1787282131,
437
+ "name": "Front Door",
438
+ "isFavorite": False,
439
+ "id": "b2c2bb88-a26e-4eb5-aae9-d6443987479f",
440
+ }
441
+
442
+
443
+ @pytest.mark.unit
444
+ def test_architectural_design_decode() -> None:
445
+ ad = ArchitecturalDesign.from_api(ARCHITECTURAL_DESIGN_SAMPLE)
446
+ assert ad.id == "b2c2bb88-a26e-4eb5-aae9-d6443987479f"
447
+ assert ad.device_id == "h2-1074-y3w9"
448
+ assert ad.name == "Front Door"
449
+ assert ad.brightness == 255
450
+ assert ad.is_favorite is False
451
+ assert len(ad.static_colors) == 1
452
+ assert ad.static_colors[0].color == 4294967295
453
+ assert ad.static_colors[0].lights == [300, 300, 307]
454
+
455
+
456
+ @pytest.mark.unit
457
+ def test_architectural_design_round_trip() -> None:
458
+ ad = ArchitecturalDesign.from_api(ARCHITECTURAL_DESIGN_SAMPLE)
459
+ wire = ad.to_api()
460
+ assert wire["id"] == ARCHITECTURAL_DESIGN_SAMPLE["id"]
461
+ assert wire["deviceId"] == ARCHITECTURAL_DESIGN_SAMPLE["deviceId"]
462
+ assert wire["name"] == "Front Door"
463
+ assert wire["staticColors"] == [{"lights": [300, 300, 307], "color": 4294967295}]
464
+
465
+
428
466
  @pytest.mark.unit
429
467
  def test_swatch_decode() -> None:
430
468
  s = Swatch.from_api(SWATCH_SAMPLE)
File without changes
File without changes
File without changes