pygemstone 0.0.2__tar.gz → 0.0.3__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.3}/PKG-INFO +2 -1
  2. {pygemstone-0.0.2 → pygemstone-0.0.3}/pyproject.toml +6 -1
  3. {pygemstone-0.0.2 → pygemstone-0.0.3}/src/pygemstone/__init__.py +4 -0
  4. pygemstone-0.0.3/src/pygemstone/color.py +96 -0
  5. {pygemstone-0.0.2 → pygemstone-0.0.3}/src/pygemstone/models.py +7 -2
  6. {pygemstone-0.0.2 → pygemstone-0.0.3/src/pygemstone.egg-info}/PKG-INFO +2 -1
  7. {pygemstone-0.0.2 → pygemstone-0.0.3}/src/pygemstone.egg-info/SOURCES.txt +2 -0
  8. {pygemstone-0.0.2 → pygemstone-0.0.3}/src/pygemstone.egg-info/requires.txt +1 -0
  9. pygemstone-0.0.3/tests/test_color.py +66 -0
  10. {pygemstone-0.0.2 → pygemstone-0.0.3}/LICENSE +0 -0
  11. {pygemstone-0.0.2 → pygemstone-0.0.3}/README.md +0 -0
  12. {pygemstone-0.0.2 → pygemstone-0.0.3}/setup.cfg +0 -0
  13. {pygemstone-0.0.2 → pygemstone-0.0.3}/src/pygemstone/__main__.py +0 -0
  14. {pygemstone-0.0.2 → pygemstone-0.0.3}/src/pygemstone/appsync.py +0 -0
  15. {pygemstone-0.0.2 → pygemstone-0.0.3}/src/pygemstone/auth.py +0 -0
  16. {pygemstone-0.0.2 → pygemstone-0.0.3}/src/pygemstone/client.py +0 -0
  17. {pygemstone-0.0.2 → pygemstone-0.0.3}/src/pygemstone/const.py +0 -0
  18. {pygemstone-0.0.2 → pygemstone-0.0.3}/src/pygemstone/device.py +0 -0
  19. {pygemstone-0.0.2 → pygemstone-0.0.3}/src/pygemstone/errors.py +0 -0
  20. {pygemstone-0.0.2 → pygemstone-0.0.3}/src/pygemstone/py.typed +0 -0
  21. {pygemstone-0.0.2 → pygemstone-0.0.3}/src/pygemstone.egg-info/dependency_links.txt +0 -0
  22. {pygemstone-0.0.2 → pygemstone-0.0.3}/src/pygemstone.egg-info/entry_points.txt +0 -0
  23. {pygemstone-0.0.2 → pygemstone-0.0.3}/src/pygemstone.egg-info/top_level.txt +0 -0
  24. {pygemstone-0.0.2 → pygemstone-0.0.3}/tests/test_appsync.py +0 -0
  25. {pygemstone-0.0.2 → pygemstone-0.0.3}/tests/test_auth.py +0 -0
  26. {pygemstone-0.0.2 → pygemstone-0.0.3}/tests/test_client.py +0 -0
  27. {pygemstone-0.0.2 → pygemstone-0.0.3}/tests/test_models.py +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.3
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.3"
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,
@@ -67,5 +68,8 @@ __all__ = [
67
68
  "GemstoneConnectionError",
68
69
  "GemstoneNotFoundError",
69
70
  "GemstoneValueError",
71
+ "color_to_hex",
72
+ "pack_color",
73
+ "unpack_color",
70
74
  "__version__",
71
75
  ]
@@ -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__ = ["unpack_color", "pack_color", "color_to_hex"]
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 "#%02x%02x%02x" % (r, g, b)
@@ -1,8 +1,13 @@
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
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pygemstone
3
- Version: 0.0.2
3
+ Version: 0.0.3
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
@@ -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)
File without changes
File without changes
File without changes