python-amazon-echo 0.2.0__tar.gz → 0.3.0__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 (32) hide show
  1. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/CHANGELOG.md +8 -0
  2. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/PKG-INFO +8 -3
  3. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/README.md +7 -2
  4. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/pyproject.toml +1 -1
  5. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/src/amazon_echo/__init__.py +1 -1
  6. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/src/amazon_echo/client.py +46 -18
  7. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/src/amazon_echo/const.py +1 -1
  8. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/tests/test_client.py +33 -0
  9. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/tests/test_models.py +1 -1
  10. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/.gitignore +0 -0
  11. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/LICENSE +0 -0
  12. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/src/amazon_echo/__main__.py +0 -0
  13. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/src/amazon_echo/auth.py +0 -0
  14. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/src/amazon_echo/endpoints.py +0 -0
  15. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/src/amazon_echo/exceptions.py +0 -0
  16. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/src/amazon_echo/local.py +0 -0
  17. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/src/amazon_echo/models.py +0 -0
  18. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/src/amazon_echo/push.py +0 -0
  19. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/src/amazon_echo/py.typed +0 -0
  20. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/tests/__init__.py +0 -0
  21. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/tests/conftest.py +0 -0
  22. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/tests/fixtures/automations.json +0 -0
  23. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/tests/fixtures/devices.json +0 -0
  24. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/tests/fixtures/graphql_endpoints.json +0 -0
  25. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/tests/fixtures/graphql_smart_home.json +0 -0
  26. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/tests/fixtures/history.json +0 -0
  27. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/tests/fixtures/notifications.json +0 -0
  28. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/tests/fixtures/np_player.json +0 -0
  29. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/tests/test_auth.py +0 -0
  30. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/tests/test_local.py +0 -0
  31. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/tests/test_push.py +0 -0
  32. {python_amazon_echo-0.2.0 → python_amazon_echo-0.3.0}/tests/test_smart_home.py +0 -0
@@ -4,6 +4,14 @@ All notable changes to this project are documented here. The format follows
4
4
  [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
5
5
  [Semantic Versioning](https://semver.org/).
6
6
 
7
+ ## [0.3.0] - 2026-11-16
8
+
9
+ ### Added
10
+
11
+ - Music alarms: `create_alarm(music=…)` takes an existing music alarm of the
12
+ account and creates a new one with the same station.
13
+ - `play_music(timer=…)`: the music stops after that many seconds.
14
+
7
15
  ## [0.2.0] - 2026-11-16
8
16
 
9
17
  ### Added
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: python-amazon-echo
3
- Version: 0.2.0
3
+ Version: 0.3.0
4
4
  Summary: Async Python client for Amazon Echo / Alexa devices: state, settings, media, notifications, lists, HTTP/2 push and LAN discovery
5
5
  Project-URL: Homepage, https://github.com/hudsonbrendon/python-amazon-echo
6
6
  Project-URL: Repository, https://github.com/hudsonbrendon/python-amazon-echo
@@ -244,6 +244,8 @@ with mocked HTTP.
244
244
  | `set_volume` (sequence pipeline) | no-op write |
245
245
  | `create_reminder`, `delete_notification` | live (a reminder 320 days ahead was created and deleted) |
246
246
  | `create_alarm` | ported |
247
+ | `create_alarm(music=…)` (music alarm that reuses the station of an existing one) | ported from Alexa Media Player's request, never sent |
248
+ | `play_music(timer=…)` (stop after that many seconds) | ported from Alexa Media Player's payload, never sent |
247
249
  | `create_timer` | ported — body inferred from field names in the app, never sent |
248
250
  | `set_wake_word` | ported |
249
251
  | `speak`, `announce`, `text_command`, `play_sound`, `play_music`, `launch_skill`, `run_routine`, `stop` | ported |
@@ -256,8 +258,8 @@ with mocked HTTP.
256
258
  | `get_smart_home_endpoints` | live read; power, brightness, colour, colour temperature, temperature, battery, contact, motion and lock states and the operation names all parsed |
257
259
  | `parse_endpoint_update` (smart-home push) | ported, not replayed live — no push stream on the test session |
258
260
  | Smart-home operations through `call_feature` (`turnOn`, `turnOff`, `setBrightness`, `setColor`, `setColorTemperature`, `setMode`, `lock`, `unlock`) | ported, not replayed live — they change a device's visible state. The request shapes of `power`, `brightness`, `lock` and `toggle` are the ones in the Alexa app; the payload of `setColorTemperature` is inferred |
259
- | `get_communication_preferences` | ported. Called live on five devices: the service answers HTTP 503 for this account whatever the device, while `/accounts` on the same host answers 200 with the same cookies |
260
- | `set_communications`, `set_announcements`, `set_drop_in` | ported, not replayed live — there was no value to write back (see the line above) |
261
+ | `get_communication_preferences` | verified live once (an Echo Plus answered `announcements: true, communications: true, drop_in: all`); otherwise the service answered HTTP 503 on about 95 % of 60+ spaced requests on 2026-11-16, on both the `.com` and the marketplace host, with cookies or a bearer token |
262
+ | `set_communications`, `set_announcements`, `set_drop_in` | ported, not replayed live — the no-op write was attempted three times each and the service answered 503 every time |
261
263
  | `get_device_preferences`, `get_kids_mode`, `get_children`, `get_kids_profile` | live read |
262
264
  | `set_kids_mode` | ported, not replayed live — it changes how a device behaves |
263
265
  | `get_guard` | live for an account without Guard (the appliance list is read, no panel is found, None); the state read is ported — the test account has no Guard |
@@ -289,6 +291,9 @@ with mocked HTTP.
289
291
  pass a naive datetime in the Echo's local time if the host lives elsewhere.
290
292
  - **Alarms have no label** in Amazon's API; `create_alarm(label=…)` is accepted
291
293
  and ignored.
294
+ - **Music alarms** can only reuse a station: `create_alarm(music=…)` takes a
295
+ music alarm that already exists on the account (create one in the Alexa app
296
+ first) and wakes with the same station. Amazon has no public search for one.
292
297
  - **`create_timer` is unverified** (see the table). Use
293
298
  `text_command(device, "set a timer for 5 minutes")` if it is rejected.
294
299
  - **Voice history** comes 10 records per call; at most 50 are fetched.
@@ -220,6 +220,8 @@ with mocked HTTP.
220
220
  | `set_volume` (sequence pipeline) | no-op write |
221
221
  | `create_reminder`, `delete_notification` | live (a reminder 320 days ahead was created and deleted) |
222
222
  | `create_alarm` | ported |
223
+ | `create_alarm(music=…)` (music alarm that reuses the station of an existing one) | ported from Alexa Media Player's request, never sent |
224
+ | `play_music(timer=…)` (stop after that many seconds) | ported from Alexa Media Player's payload, never sent |
223
225
  | `create_timer` | ported — body inferred from field names in the app, never sent |
224
226
  | `set_wake_word` | ported |
225
227
  | `speak`, `announce`, `text_command`, `play_sound`, `play_music`, `launch_skill`, `run_routine`, `stop` | ported |
@@ -232,8 +234,8 @@ with mocked HTTP.
232
234
  | `get_smart_home_endpoints` | live read; power, brightness, colour, colour temperature, temperature, battery, contact, motion and lock states and the operation names all parsed |
233
235
  | `parse_endpoint_update` (smart-home push) | ported, not replayed live — no push stream on the test session |
234
236
  | Smart-home operations through `call_feature` (`turnOn`, `turnOff`, `setBrightness`, `setColor`, `setColorTemperature`, `setMode`, `lock`, `unlock`) | ported, not replayed live — they change a device's visible state. The request shapes of `power`, `brightness`, `lock` and `toggle` are the ones in the Alexa app; the payload of `setColorTemperature` is inferred |
235
- | `get_communication_preferences` | ported. Called live on five devices: the service answers HTTP 503 for this account whatever the device, while `/accounts` on the same host answers 200 with the same cookies |
236
- | `set_communications`, `set_announcements`, `set_drop_in` | ported, not replayed live — there was no value to write back (see the line above) |
237
+ | `get_communication_preferences` | verified live once (an Echo Plus answered `announcements: true, communications: true, drop_in: all`); otherwise the service answered HTTP 503 on about 95 % of 60+ spaced requests on 2026-11-16, on both the `.com` and the marketplace host, with cookies or a bearer token |
238
+ | `set_communications`, `set_announcements`, `set_drop_in` | ported, not replayed live — the no-op write was attempted three times each and the service answered 503 every time |
237
239
  | `get_device_preferences`, `get_kids_mode`, `get_children`, `get_kids_profile` | live read |
238
240
  | `set_kids_mode` | ported, not replayed live — it changes how a device behaves |
239
241
  | `get_guard` | live for an account without Guard (the appliance list is read, no panel is found, None); the state read is ported — the test account has no Guard |
@@ -265,6 +267,9 @@ with mocked HTTP.
265
267
  pass a naive datetime in the Echo's local time if the host lives elsewhere.
266
268
  - **Alarms have no label** in Amazon's API; `create_alarm(label=…)` is accepted
267
269
  and ignored.
270
+ - **Music alarms** can only reuse a station: `create_alarm(music=…)` takes a
271
+ music alarm that already exists on the account (create one in the Alexa app
272
+ first) and wakes with the same station. Amazon has no public search for one.
268
273
  - **`create_timer` is unverified** (see the table). Use
269
274
  `text_command(device, "set a timer for 5 minutes")` if it is rejected.
270
275
  - **Voice history** comes 10 records per call; at most 50 are fetched.
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "python-amazon-echo"
7
- version = "0.2.0"
7
+ version = "0.3.0"
8
8
  description = "Async Python client for Amazon Echo / Alexa devices: state, settings, media, notifications, lists, HTTP/2 push and LAN discovery"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -30,7 +30,7 @@ from .models import (
30
30
  )
31
31
  from .push import PushClient, PushEvent
32
32
 
33
- __version__ = "0.2.0"
33
+ __version__ = "0.3.0"
34
34
 
35
35
  __all__ = [
36
36
  "Account",
@@ -1425,16 +1425,32 @@ class AmazonEchoClient:
1425
1425
  )
1426
1426
  )
1427
1427
 
1428
- async def play_music(self, device: Device, provider_id: str, phrase: str) -> None:
1429
- """Play ``phrase`` from a music provider (see :meth:`get_music_providers`)."""
1428
+ async def play_music(
1429
+ self,
1430
+ device: Device,
1431
+ provider_id: str,
1432
+ phrase: str,
1433
+ *,
1434
+ timer: int | None = None,
1435
+ ) -> None:
1436
+ """Play ``phrase`` from a music provider (see :meth:`get_music_providers`).
1437
+
1438
+ Args:
1439
+ device: The device that plays.
1440
+ provider_id: A key of :meth:`get_music_providers`.
1441
+ phrase: What to search for.
1442
+ timer: Stop after this many seconds (a sleep timer).
1443
+
1444
+ """
1445
+ payload: dict[str, Any] = {
1446
+ "searchPhrase": phrase,
1447
+ "sanitizedSearchPhrase": phrase,
1448
+ "musicProviderId": provider_id,
1449
+ }
1450
+ if timer:
1451
+ payload["waitTimeInSeconds"] = timer
1430
1452
  await self._run(
1431
- await self._node(
1432
- device,
1433
- "Alexa.Music.PlaySearchPhrase",
1434
- searchPhrase=phrase,
1435
- sanitizedSearchPhrase=phrase,
1436
- musicProviderId=provider_id,
1437
- )
1453
+ await self._node(device, "Alexa.Music.PlaySearchPhrase", **payload)
1438
1454
  )
1439
1455
 
1440
1456
  async def launch_skill(self, device: Device, skill_id: str) -> None:
@@ -1582,6 +1598,7 @@ class AmazonEchoClient:
1582
1598
  *,
1583
1599
  label: str | None = None,
1584
1600
  recurrence: str | None = None,
1601
+ music: Notification | None = None,
1585
1602
  ) -> Notification:
1586
1603
  """Create an alarm.
1587
1604
 
@@ -1592,6 +1609,14 @@ class AmazonEchoClient:
1592
1609
  label: Not supported by Amazon for alarms; accepted and ignored.
1593
1610
  recurrence: ``DAILY``, ``WEEKDAYS``, ``WEEKENDS``, ``WEEKLY`` or a
1594
1611
  day list such as ``MO,WE,FR``.
1612
+ music: An existing music alarm of the account; the new alarm
1613
+ wakes with the same station. Amazon has no public way to
1614
+ search for a station, so one that was picked in the Alexa app
1615
+ is reused (the ``MUSIC-<id>`` tone :meth:`enable_alarm` sends;
1616
+ this request has not been replayed against Amazon).
1617
+
1618
+ Raises:
1619
+ AmazonEchoNotSupportedError: ``music`` is not a music alarm.
1595
1620
 
1596
1621
  """
1597
1622
  del label
@@ -1599,17 +1624,20 @@ class AmazonEchoClient:
1599
1624
  trigger: dict[str, Any] = {"scheduledTime": local.isoformat(timespec="seconds")}
1600
1625
  if recurrence:
1601
1626
  trigger["recurrence"] = _recurrence_rule(recurrence, local)
1627
+ body: dict[str, Any] = {
1628
+ "trigger": trigger,
1629
+ "extensions": [],
1630
+ "endpointId": f"{device.serial}@{device.device_type}",
1631
+ }
1632
+ if music is not None:
1633
+ if not (music_id := music.raw.get("musicAlarmId")):
1634
+ raise AmazonEchoNotSupportedError("Not a music alarm")
1635
+ body["assets"] = [{"type": "TONE", "assetId": f"MUSIC-{music_id}"}]
1602
1636
  known = {item.id for item in await self.get_notifications()}
1603
- await self._alerts(
1604
- "POST",
1605
- "alarms",
1606
- {
1607
- "trigger": trigger,
1608
- "extensions": [],
1609
- "endpointId": f"{device.serial}@{device.device_type}",
1610
- },
1637
+ await self._alerts("POST", "alarms", body)
1638
+ return await self._find_new(
1639
+ device, "alarm" if music is None else "music_alarm", known
1611
1640
  )
1612
- return await self._find_new(device, "alarm", known)
1613
1641
 
1614
1642
  async def create_reminder(
1615
1643
  self, device: Device, when: datetime, label: str
@@ -4,7 +4,7 @@ from __future__ import annotations
4
4
 
5
5
  from typing import Any, Final
6
6
 
7
- VERSION: Final = "0.2.0"
7
+ VERSION: Final = "0.3.0"
8
8
 
9
9
  # Identity of the Alexa iOS app, which is what a registration impersonates.
10
10
  APP_NAME: Final = "Amazon Echo for Home Assistant"
@@ -1109,6 +1109,9 @@ async def test_play_music(client, session, office):
1109
1109
  "sanitizedSearchPhrase": "jazz",
1110
1110
  "musicProviderId": "SPOTIFY",
1111
1111
  }
1112
+ # a sleep timer: the music stops by itself
1113
+ await client.play_music(office, "SPOTIFY", "jazz", timer=600)
1114
+ assert node_of(session)["operationPayload"]["waitTimeInSeconds"] == 600
1112
1115
 
1113
1116
 
1114
1117
  async def test_launch_skill(client, session, office):
@@ -1260,6 +1263,36 @@ async def test_create_alarm_that_never_shows_up(client, session, office):
1260
1263
  assert "recurrence" not in session.sent("/v1/alerts/alarms")[0]["json"]["trigger"]
1261
1264
 
1262
1265
 
1266
+ async def test_create_music_alarm(client, session, office):
1267
+ new = {
1268
+ "id": "A18O6U1UQFJ0XK-G000TEST00000001-new-music",
1269
+ "type": "Alarm",
1270
+ "status": "ON",
1271
+ "deviceSerialNumber": "G000TEST00000001",
1272
+ "deviceType": "A18O6U1UQFJ0XK",
1273
+ "musicAlarmId": "music-1",
1274
+ "createdDate": 1_800_000_000_000,
1275
+ }
1276
+ session.add("GET", "/api/notifications", _listing(), _listing(), _listing(new))
1277
+ session.add("GET", "/api/endpoints", {"alexaApiUrl": "https://api.amazonalexa.com"})
1278
+ session.add("POST", "/v1/alerts/alarms", None)
1279
+ alarm, _, _, music, _ = await client.get_notifications()
1280
+ created = await client.create_alarm(
1281
+ office, datetime(2027, 1, 15, 7, 0), music=music
1282
+ )
1283
+ assert session.sent("/v1/alerts/alarms")[0]["json"] == {
1284
+ "trigger": {"scheduledTime": "2027-01-15T07:00:00"},
1285
+ "extensions": [],
1286
+ "endpointId": "G000TEST00000001@A18O6U1UQFJ0XK",
1287
+ "assets": [{"type": "TONE", "assetId": "MUSIC-music-1"}],
1288
+ }
1289
+ assert (created.id, created.kind) == (new["id"], "music_alarm")
1290
+ # an ordinary alarm has no station to reuse
1291
+ with pytest.raises(AmazonEchoNotSupportedError, match="Not a music alarm"):
1292
+ await client.create_alarm(office, datetime(2027, 1, 15, 7, 0), music=alarm)
1293
+ assert len(session.sent("/v1/alerts/alarms")) == 1
1294
+
1295
+
1263
1296
  async def test_alerts_api_missing(client, session, office):
1264
1297
  session.add("GET", "/api/notifications", _listing())
1265
1298
  session.add("GET", "/api/endpoints", {})
@@ -7,7 +7,7 @@ from amazon_echo import Device, Notification, PushEvent
7
7
 
8
8
 
9
9
  def test_public_api():
10
- assert amazon_echo.__version__ == "0.2.0"
10
+ assert amazon_echo.__version__ == "0.3.0"
11
11
  for name in amazon_echo.__all__:
12
12
  assert hasattr(amazon_echo, name)
13
13
  assert issubclass(