tinkly 0.2.0__tar.gz → 0.2.2__tar.gz

tinkly-0.2.2/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: tinkly
+Version: 0.2.2
+Summary: Low-level Twinkly discovery, authentication, HTTP, and realtime UDP transport
+Author-email: Tom Ritchford <tom@swirly.com>
+Project-URL: Documentation, https://rec.github.io/tinkly/
+Project-URL: Repository, https://github.com/rec/tinkly
+Project-URL: Issues, https://github.com/rec/tinkly/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# tinkly: a tiny interface to Twinkly v2 lights
+
+I love the Twinkly lights but the [xled library](https://github.com/scrool/xled) is
+filled with complicated cruft which obscures the actual communication layer, and seems
+to no longer be in development.
+
+In particular, xled has a totally unnecessary ZMQ queue that
+slows everything down and prevents two clients from existing.
+
+I re-implemented just the Twinkly communication part, and left all the other
+parts behind. In particular, there is no CLI - for that, you'll have to see my
+upcoming general project, "lyte".
+
+Check out https://xled-docs.readthedocs.io/en/latest/ for more information about the
+API protocol.
+
+## Device communication
+
+This package provides UDP discovery, authentication, HTTP endpoint access for generation
+2 Twinkly lights.
+
+```python
+from tinkly.client import TwinklyClient
+from tinkly.discovery import discover
+from tinkly.frame import send_frame
+
+devices = list(discover(timeout=2.0))
+client = TwinklyClient(host=devices[0].ip_address)
+info = client.get('gestalt', authenticated=False).data
+client.mac = str(info['mac'])
+token = client.authenticate()
+
+client.set_realtime_mode()
+frame = bytes((255, 0, 0)) * int(str(info['number_of_led']))
+send_frame(client.host, token.value, frame)
+client.set_off_mode()
+```
+
+## Frame buffers
+
+`lyte` uses `numpy`, but I decided not to make that a dependency. Instead, we use
+Python's buffer protocol `collections.abc.Buffer`. The input is C-style unsigned bytes
+in RGB order, with three bytes per LED.  Supported inputs include `bytes`, `bytearray`,
+`array.array('B')`, `memoryview`, and C-contiguous NumPy `uint8` arrays.
+
+## The API
+
+https://rec.github.io/tinkly/

{tinkly-0.2.0 → tinkly-0.2.2}/README.md

@@ -11,6 +11,9 @@ I re-implemented just the Twinkly communication part, and left all the other
 parts behind. In particular, there is no CLI - for that, you'll have to see my
 upcoming general project, "lyte".
 
+Check out https://xled-docs.readthedocs.io/en/latest/ for more information about the
+API protocol.
+
 ## Device communication
 
 This package provides UDP discovery, authentication, HTTP endpoint access for generation

{tinkly-0.2.0 → tinkly-0.2.2}/pyproject.toml

@@ -4,9 +4,23 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tinkly"
-version = "0.2.0"
+version = "0.2.2"
 description = "Low-level Twinkly discovery, authentication, HTTP, and realtime UDP transport"
+readme = "README.md"
+authors = [{ name = "Tom Ritchford", email = "tom@swirly.com" }]
 requires-python = ">=3.12"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+]
+
+[project.urls]
+Documentation = "https://rec.github.io/tinkly/"
+Repository = "https://github.com/rec/tinkly"
+Issues = "https://github.com/rec/tinkly/issues"
 
 [tool.setuptools.packages.find]
 where = ["."]
@@ -15,8 +29,12 @@ include = ["tinkly*"]
 [tool.ruff.format]
 quote-style = "single"
 
+[tool.ruff.lint]
+select = ["B", "E", "F", "I"]
+
 [tool.pytest.ini_options]
 pythonpath = ["."]
+testpaths = ["tests"]
 
 [dependency-groups]
 dev = [
@@ -29,6 +47,9 @@ dev = [
     "tyro",
 ]
 
+[tool.uv]
+exclude-newer = "1 week"
+
 [tool.uv.sources]
 reccy = { git = "ssh://git@github.com/rec/reccy.git", branch = "main" }
 

{tinkly-0.2.0 → tinkly-0.2.2}/scripts/griffe_tinkly.py

@@ -37,7 +37,7 @@ class EndpointProperties(griffe.Extension):
         """Add property labels, response types, and HTTP behavior to factory calls.
 
         Only assignments on tinkly.client.TwinklyClient are processed. Preserve
-        any endpoint-specific attribute docstring after the generated details.
+        endpoint-specific descriptions; shared behavior belongs on the class.
         """
         if attr.parent is None or attr.parent.path != 'tinkly.client.TwinklyClient':
             return
@@ -61,22 +61,14 @@ class EndpointProperties(griffe.Extension):
             True,
         )
         writable = call.func.id == 'setter'
-        description = (
-            f'HTTP endpoint `GET {path}`.\n\n'
-            'Each read sends a fresh request and returns a '
-            '`tinkly.client.TwinklyResponse` containing `http_status` and `data`.\n\n'
-            f'Authentication is {"required" if authenticated else "not required"}.'
-        )
+        description = f'`GET {path}`'
         if writable:
-            description += (
-                f'\n\nAssign a `dict[str, object]` JSON body to send `POST {path}`. '
-                'Assignment does not return the response; use `post()` when needed.'
-            )
-        else:
-            description += '\n\nThis property is read-only.'
-        description += '\n\nRequest errors propagate to the caller.'
+            description += f', `POST {path}`'
+        description += '.'
+        if not authenticated:
+            description += ' Authentication is not required.'
         if attr.docstring is not None:
-            description += f'\n\n{attr.docstring.value}'
+            description = f'{attr.docstring.value}\n\n{description}'
 
         attr.labels.difference_update({'class-attribute', 'instance-attribute'})
         attr.labels.add('property')

{tinkly-0.2.0 → tinkly-0.2.2}/tests/test_documentation.py

@@ -28,15 +28,31 @@ class DocumentationTests(unittest.TestCase):
         self.assertIsNone(brightness.value)
         self.assertIn('GET led/out/brightness', brightness.docstring.value)
         self.assertIn('POST led/out/brightness', brightness.docstring.value)
-        self.assertIn('dict[str, object]', brightness.docstring.value)
-        self.assertIn('Authentication is required', brightness.docstring.value)
+        self.assertIn('dict[str, object]', client.docstring.value)
+        self.assertIn('Authentication is required', client.docstring.value)
+        self.assertIn('Request errors propagate', client.docstring.value)
+        self.assertIn('read-only', client.docstring.value)
+        self.assertIn('http_status and data', client.docstring.value)
+        self.assertIn('output brightness', brightness.docstring.value)
+        for attribute in client.attributes.values():
+            if 'property' in attribute.labels:
+                with self.subTest(property=attribute.name):
+                    self.assertNotIn('Each read sends', attribute.docstring.value)
+                    self.assertNotIn(
+                        'Authentication is required', attribute.docstring.value
+                    )
+                    self.assertNotIn(
+                        'This property is read-only', attribute.docstring.value
+                    )
+                    self.assertNotIn(
+                        'Request errors propagate', attribute.docstring.value
+                    )
         for attribute in (firmware, status):
             with self.subTest(property=attribute.name):
                 self.assertEqual(attribute.labels, {'property'})
                 self.assertIn(
                     'Authentication is not required', attribute.docstring.value
                 )
-                self.assertIn('read-only', attribute.docstring.value)
         self.assertIn('GET fw/version', firmware.docstring.value)
         self.assertIn('GET status', status.docstring.value)
         self.assertEqual(

{tinkly-0.2.0 → tinkly-0.2.2}/tinkly/client.py

@@ -81,9 +81,14 @@ class AuthToken:
 class TwinklyClient:
     """Synchronous HTTP client for a single Twinkly device.
 
-    Endpoint properties return TwinklyResponse records on every read. Writable
-    properties POST assigned JSON dictionaries. Authentication is automatic
-    for protected endpoints. Each request opens and closes an HTTP connection;
+    Each endpoint property read sends a fresh GET request and returns a
+    TwinklyResponse containing http_status and data. Properties marked writable
+    accept a dict[str, object] JSON body and POST assignments; assignment discards
+    the response, so use post() when it is needed. Other properties are read-only.
+    Authentication is required and obtained automatically unless stated otherwise.
+    Request errors propagate to the caller.
+
+    Each request opens and closes an HTTP connection;
     retries, realtime frame pacing, and reconnection belong to the caller.
     Serialize all use of a client; instances are not thread-safe.
     """

tinkly-0.2.2/tinkly.egg-info/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: tinkly
+Version: 0.2.2
+Summary: Low-level Twinkly discovery, authentication, HTTP, and realtime UDP transport
+Author-email: Tom Ritchford <tom@swirly.com>
+Project-URL: Documentation, https://rec.github.io/tinkly/
+Project-URL: Repository, https://github.com/rec/tinkly
+Project-URL: Issues, https://github.com/rec/tinkly/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# tinkly: a tiny interface to Twinkly v2 lights
+
+I love the Twinkly lights but the [xled library](https://github.com/scrool/xled) is
+filled with complicated cruft which obscures the actual communication layer, and seems
+to no longer be in development.
+
+In particular, xled has a totally unnecessary ZMQ queue that
+slows everything down and prevents two clients from existing.
+
+I re-implemented just the Twinkly communication part, and left all the other
+parts behind. In particular, there is no CLI - for that, you'll have to see my
+upcoming general project, "lyte".
+
+Check out https://xled-docs.readthedocs.io/en/latest/ for more information about the
+API protocol.
+
+## Device communication
+
+This package provides UDP discovery, authentication, HTTP endpoint access for generation
+2 Twinkly lights.
+
+```python
+from tinkly.client import TwinklyClient
+from tinkly.discovery import discover
+from tinkly.frame import send_frame
+
+devices = list(discover(timeout=2.0))
+client = TwinklyClient(host=devices[0].ip_address)
+info = client.get('gestalt', authenticated=False).data
+client.mac = str(info['mac'])
+token = client.authenticate()
+
+client.set_realtime_mode()
+frame = bytes((255, 0, 0)) * int(str(info['number_of_led']))
+send_frame(client.host, token.value, frame)
+client.set_off_mode()
+```
+
+## Frame buffers
+
+`lyte` uses `numpy`, but I decided not to make that a dependency. Instead, we use
+Python's buffer protocol `collections.abc.Buffer`. The input is C-style unsigned bytes
+in RGB order, with three bytes per LED.  Supported inputs include `bytes`, `bytearray`,
+`array.array('B')`, `memoryview`, and C-contiguous NumPy `uint8` arrays.
+
+## The API
+
+https://rec.github.io/tinkly/

{tinkly-0.2.0 → tinkly-0.2.2}/uv.lock

@@ -7,7 +7,7 @@ resolution-markers = [
 ]
 
 [options]
-exclude-newer = "2026-11-04T19:29:17.139037Z"
+exclude-newer = "2026-11-04T19:41:26.290514Z"
 exclude-newer-span = "P1W"
 
 [[package]]
@@ -327,7 +327,7 @@ wheels = [
 
 [[package]]
 name = "tinkly"
-version = "0.2.0"
+version = "0.2.2"
 source = { editable = "." }
 
 [package.dev-dependencies]

tinkly-0.2.0/PKG-INFO

@@ -1,5 +0,0 @@
-Metadata-Version: 2.4
-Name: tinkly
-Version: 0.2.0
-Summary: Low-level Twinkly discovery, authentication, HTTP, and realtime UDP transport
-Requires-Python: >=3.12

tinkly-0.2.0/tinkly.egg-info/PKG-INFO

@@ -1,5 +0,0 @@
-Metadata-Version: 2.4
-Name: tinkly
-Version: 0.2.0
-Summary: Low-level Twinkly discovery, authentication, HTTP, and realtime UDP transport
-Requires-Python: >=3.12