python-amazon-echo 0.1.1__tar.gz → 0.2.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.1.1 → python_amazon_echo-0.2.0}/CHANGELOG.md +30 -0
  2. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/PKG-INFO +67 -6
  3. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/README.md +66 -5
  4. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/pyproject.toml +1 -1
  5. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/src/amazon_echo/__init__.py +5 -1
  6. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/src/amazon_echo/client.py +494 -71
  7. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/src/amazon_echo/const.py +74 -1
  8. python_amazon_echo-0.2.0/src/amazon_echo/endpoints.py +191 -0
  9. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/src/amazon_echo/models.py +43 -0
  10. python_amazon_echo-0.2.0/tests/fixtures/graphql_smart_home.json +995 -0
  11. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/tests/test_models.py +1 -1
  12. python_amazon_echo-0.2.0/tests/test_smart_home.py +723 -0
  13. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/.gitignore +0 -0
  14. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/LICENSE +0 -0
  15. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/src/amazon_echo/__main__.py +0 -0
  16. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/src/amazon_echo/auth.py +0 -0
  17. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/src/amazon_echo/exceptions.py +0 -0
  18. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/src/amazon_echo/local.py +0 -0
  19. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/src/amazon_echo/push.py +0 -0
  20. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/src/amazon_echo/py.typed +0 -0
  21. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/tests/__init__.py +0 -0
  22. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/tests/conftest.py +0 -0
  23. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/tests/fixtures/automations.json +0 -0
  24. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/tests/fixtures/devices.json +0 -0
  25. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/tests/fixtures/graphql_endpoints.json +0 -0
  26. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/tests/fixtures/history.json +0 -0
  27. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/tests/fixtures/notifications.json +0 -0
  28. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/tests/fixtures/np_player.json +0 -0
  29. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/tests/test_auth.py +0 -0
  30. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/tests/test_client.py +0 -0
  31. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/tests/test_local.py +0 -0
  32. {python_amazon_echo-0.1.1 → python_amazon_echo-0.2.0}/tests/test_push.py +0 -0
@@ -4,6 +4,36 @@ 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.2.0] - 2026-11-16
8
+
9
+ ### Added
10
+
11
+ - Smart home: `get_smart_home_endpoints()` returns every device linked to the
12
+ account as an `Endpoint` (category, manufacturer, model, the operations it
13
+ accepts and its state: power, brightness, colour, colour temperature,
14
+ temperature, humidity, battery, contact, motion, lock, light shows).
15
+ `get_endpoint_states()` now also reports `illuminance`, `motion`, `humidity`
16
+ and, for the Amazon Air Quality Monitor, `pm25`, `pm10`, `voc`, `co`,
17
+ `air_quality` and `aqm_led`. Both share one GraphQL request when called
18
+ within 5 s. `parse_endpoint_update()` decodes the smart-home push event.
19
+ - Communication preferences per device: `get_communication_preferences`,
20
+ `set_communications`, `set_announcements`, `set_drop_in`.
21
+ - Alexa Guard: `get_guard`, `set_guard` and the `Guard` model.
22
+ - Sequences: `info_skill` (17 "tell me…" skills, see `INFO_SKILLS`),
23
+ `send_sequence` for any node type, `send_mobile_push`,
24
+ `send_drop_in_notification`, and `announce(method="all" | "speak" | "show")`.
25
+ - Alarms: `enable_alarm`, `disable_alarm`, `skip_next_alarm`.
26
+ - Amazon Kids: `get_children`, `get_kids_mode`, `get_kids_profile`,
27
+ `set_kids_mode`.
28
+ - `get_device_preferences` (locale, time zone, temperature scale by device),
29
+ `set_background_image`.
30
+ - `VoiceRecord.person_type`.
31
+
32
+ ### Changed
33
+
34
+ - A temperature of -280 (what Amazon reports while a sensor calibrates) is
35
+ returned as None.
36
+
7
37
  ## [0.1.1] - 2026-11-16
8
38
 
9
39
  ### Fixed
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: python-amazon-echo
3
- Version: 0.1.1
3
+ Version: 0.2.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
@@ -52,9 +52,22 @@ on the local network. It is not affiliated with Amazon.
52
52
  volume, default alarm sound, ascending alarm, wake word, AUX direction, whisper
53
53
  mode, adaptive volume and any per-device setting key (speaking rate, time zone,
54
54
  captions, …).
55
- - **Actions.** Volume, stop, speak, announce, text command, sounds, music,
56
- skills, routines, transport commands, Bluetooth, reboot.
57
- - **Alarms, timers and reminders.** List all, create and delete.
55
+ - **Actions.** Volume, stop, speak, announce (spoken, shown or both), text
56
+ command, sounds, music, skills, routines, the "tell me…" info skills (weather,
57
+ traffic, flash briefing, a joke…), any other behavior node type, transport
58
+ commands, Bluetooth, reboot, Echo Show background image.
59
+ - **Notifications to the Alexa app.** A mobile push, or one that opens Drop In.
60
+ - **Communication preferences.** Calls and messages, announcements and Drop In
61
+ per device.
62
+ - **Amazon Kids.** The child profiles of the household, which one a device is
63
+ assigned to, and switching a device into or out of Kids mode.
64
+ - **Alarms, timers and reminders.** List all, create, delete; switch an alarm
65
+ on or off and skip its next ring.
66
+ - **Smart home.** Every device linked to the account (lamps, plugs, sensors,
67
+ locks, Echo Glow, the Air Quality Monitor) with its state and the operations
68
+ it accepts; sensors of the Echos themselves (illuminance, motion, humidity);
69
+ state changes pushed by Amazon decoded into the same values.
70
+ - **Alexa Guard.** Read the panel, arm (away) and disarm (home).
58
71
  - **Lists.** Shopping, to-do and custom lists with full item CRUD.
59
72
  - **Voice history.**
60
73
  - **Push.** One HTTP/2 stream delivers volume, playback, do-not-disturb,
@@ -121,6 +134,26 @@ await push.start() # background task, reconnects with back-off 5·2ⁿ s (≤ 6
121
134
  await push.stop()
122
135
  ```
123
136
 
137
+ Smart home:
138
+
139
+ ```python
140
+ for endpoint in await client.get_smart_home_endpoints():
141
+ print(endpoint.name, endpoint.category, endpoint.state)
142
+
143
+ lamp = next(e for e in await client.get_smart_home_endpoints() if e.category == "LIGHT")
144
+ if lamp.supports("brightness", "setBrightness"):
145
+ await client.call_feature(
146
+ lamp.id, "brightness", "setBrightness", payload={"brightness": 40}
147
+ )
148
+ ```
149
+
150
+ `endpoint.state` uses the keys documented in
151
+ `amazon_echo.endpoints.parse_features` (`power`, `brightness`, `color`,
152
+ `color_temperature`, `temperature`, `humidity`, `battery`, `contact`, `motion`,
153
+ `lock`…); a key is there when the device has the feature, and is None while
154
+ Amazon cannot read it. `get_endpoint_states()` and `get_smart_home_endpoints()`
155
+ share one request when called within 5 seconds.
156
+
124
157
  LAN:
125
158
 
126
159
  ```python
@@ -184,8 +217,9 @@ Credentials are read from `~/.config/amazon-echo/credentials.json`
184
217
 
185
218
  ## Verification
186
219
 
187
- How each part was checked against a real amazon.com.br account on 2026-11-15. Everything is also covered by unit tests with mocked
188
- HTTP.
220
+ How each part was checked against a real amazon.com.br account on 2026-11-15
221
+ (the 0.2.0 additions on 2026-11-16). Everything is also covered by unit tests
222
+ with mocked HTTP.
189
223
 
190
224
  - **live read** — called against Amazon through this library, answer parsed.
191
225
  - **no-op write** — the value just read was written back to one Echo Plus and
@@ -218,6 +252,19 @@ HTTP.
218
252
  | `add_list_item`, `update_list_item`, `delete_list_item` | ported |
219
253
  | `get_voice_history` | live read |
220
254
  | `call_feature` | ported |
255
+ | `get_endpoint_states` with the 0.2.0 query (illuminance, motion, humidity, air quality) | live read: a few hundred endpoints, no GraphQL error. Four devices advertise a light sensor and report no value; no device of the account reports motion, humidity or air quality, so those are unit tested only |
256
+ | `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
+ | `parse_endpoint_update` (smart-home push) | ported, not replayed live — no push stream on the test session |
258
+ | 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_device_preferences`, `get_kids_mode`, `get_children`, `get_kids_profile` | live read |
262
+ | `set_kids_mode` | ported, not replayed live — it changes how a device behaves |
263
+ | `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 |
264
+ | `set_guard` | ported, not replayed live — Guard was not touched |
265
+ | `info_skill`, `send_sequence`, `send_mobile_push`, `send_drop_in_notification`, `announce(method=…)` | ported, not replayed live — audible, or visible on a phone |
266
+ | `enable_alarm`, `disable_alarm`, `skip_next_alarm` | ported, not replayed live |
267
+ | `set_background_image` | ported, not replayed live — it changes what an Echo Show displays |
221
268
  | `PushClient` | handshake live (HTTP/2, 200, multipart boundary). the stream is then closed within ~1 s because the test session shares its registration with a running `alexa_media` (one stream per registration, see *Known limitations*); event parsing is unit tested only |
222
269
  | `probe_local`, `is_reachable` | live (two Echo models answer, a smart TV of another brand returns None) |
223
270
 
@@ -250,6 +297,20 @@ HTTP.
250
297
  sends `PUSH_NOTIFICATION_CHANGE`).
251
298
  - `devices-v2` no longer reports MAC addresses or battery levels for most
252
299
  devices; the MAC comes from GraphQL and is missing for apps and groups.
300
+ - **Communication preferences** come from a service that fails for some
301
+ accounts (HTTP 503 on the test account). The call is not retried and raises
302
+ `AmazonEchoRateLimitError`; treat it as "not available for this device".
303
+ - **Guard** is looked up once per client: an account that gets Guard later is
304
+ noticed by a new client. The free version of Guard was retired by Amazon in
305
+ most countries; the code follows `alexapy` and could not be run.
306
+ - **Smart-home state** is what Amazon last heard from the device's own cloud.
307
+ A value Amazon cannot read is None, and `reachable` is False for a device its
308
+ cloud reports offline.
309
+ - **Locks.** Amazon offers `unlock` only for some locks; check
310
+ `endpoint.supports("lock", "unlock")`.
311
+ - **Deleting voice history is not implemented.** The only endpoint the existing
312
+ clients use for it, `/api/activities`, answers 404 since Amazon moved the
313
+ history to the privacy hub.
253
314
  - Amazon can change or remove any of this without notice.
254
315
 
255
316
  ## Development
@@ -28,9 +28,22 @@ on the local network. It is not affiliated with Amazon.
28
28
  volume, default alarm sound, ascending alarm, wake word, AUX direction, whisper
29
29
  mode, adaptive volume and any per-device setting key (speaking rate, time zone,
30
30
  captions, …).
31
- - **Actions.** Volume, stop, speak, announce, text command, sounds, music,
32
- skills, routines, transport commands, Bluetooth, reboot.
33
- - **Alarms, timers and reminders.** List all, create and delete.
31
+ - **Actions.** Volume, stop, speak, announce (spoken, shown or both), text
32
+ command, sounds, music, skills, routines, the "tell me…" info skills (weather,
33
+ traffic, flash briefing, a joke…), any other behavior node type, transport
34
+ commands, Bluetooth, reboot, Echo Show background image.
35
+ - **Notifications to the Alexa app.** A mobile push, or one that opens Drop In.
36
+ - **Communication preferences.** Calls and messages, announcements and Drop In
37
+ per device.
38
+ - **Amazon Kids.** The child profiles of the household, which one a device is
39
+ assigned to, and switching a device into or out of Kids mode.
40
+ - **Alarms, timers and reminders.** List all, create, delete; switch an alarm
41
+ on or off and skip its next ring.
42
+ - **Smart home.** Every device linked to the account (lamps, plugs, sensors,
43
+ locks, Echo Glow, the Air Quality Monitor) with its state and the operations
44
+ it accepts; sensors of the Echos themselves (illuminance, motion, humidity);
45
+ state changes pushed by Amazon decoded into the same values.
46
+ - **Alexa Guard.** Read the panel, arm (away) and disarm (home).
34
47
  - **Lists.** Shopping, to-do and custom lists with full item CRUD.
35
48
  - **Voice history.**
36
49
  - **Push.** One HTTP/2 stream delivers volume, playback, do-not-disturb,
@@ -97,6 +110,26 @@ await push.start() # background task, reconnects with back-off 5·2ⁿ s (≤ 6
97
110
  await push.stop()
98
111
  ```
99
112
 
113
+ Smart home:
114
+
115
+ ```python
116
+ for endpoint in await client.get_smart_home_endpoints():
117
+ print(endpoint.name, endpoint.category, endpoint.state)
118
+
119
+ lamp = next(e for e in await client.get_smart_home_endpoints() if e.category == "LIGHT")
120
+ if lamp.supports("brightness", "setBrightness"):
121
+ await client.call_feature(
122
+ lamp.id, "brightness", "setBrightness", payload={"brightness": 40}
123
+ )
124
+ ```
125
+
126
+ `endpoint.state` uses the keys documented in
127
+ `amazon_echo.endpoints.parse_features` (`power`, `brightness`, `color`,
128
+ `color_temperature`, `temperature`, `humidity`, `battery`, `contact`, `motion`,
129
+ `lock`…); a key is there when the device has the feature, and is None while
130
+ Amazon cannot read it. `get_endpoint_states()` and `get_smart_home_endpoints()`
131
+ share one request when called within 5 seconds.
132
+
100
133
  LAN:
101
134
 
102
135
  ```python
@@ -160,8 +193,9 @@ Credentials are read from `~/.config/amazon-echo/credentials.json`
160
193
 
161
194
  ## Verification
162
195
 
163
- How each part was checked against a real amazon.com.br account on 2026-11-15. Everything is also covered by unit tests with mocked
164
- HTTP.
196
+ How each part was checked against a real amazon.com.br account on 2026-11-15
197
+ (the 0.2.0 additions on 2026-11-16). Everything is also covered by unit tests
198
+ with mocked HTTP.
165
199
 
166
200
  - **live read** — called against Amazon through this library, answer parsed.
167
201
  - **no-op write** — the value just read was written back to one Echo Plus and
@@ -194,6 +228,19 @@ HTTP.
194
228
  | `add_list_item`, `update_list_item`, `delete_list_item` | ported |
195
229
  | `get_voice_history` | live read |
196
230
  | `call_feature` | ported |
231
+ | `get_endpoint_states` with the 0.2.0 query (illuminance, motion, humidity, air quality) | live read: a few hundred endpoints, no GraphQL error. Four devices advertise a light sensor and report no value; no device of the account reports motion, humidity or air quality, so those are unit tested only |
232
+ | `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
+ | `parse_endpoint_update` (smart-home push) | ported, not replayed live — no push stream on the test session |
234
+ | 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_device_preferences`, `get_kids_mode`, `get_children`, `get_kids_profile` | live read |
238
+ | `set_kids_mode` | ported, not replayed live — it changes how a device behaves |
239
+ | `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 |
240
+ | `set_guard` | ported, not replayed live — Guard was not touched |
241
+ | `info_skill`, `send_sequence`, `send_mobile_push`, `send_drop_in_notification`, `announce(method=…)` | ported, not replayed live — audible, or visible on a phone |
242
+ | `enable_alarm`, `disable_alarm`, `skip_next_alarm` | ported, not replayed live |
243
+ | `set_background_image` | ported, not replayed live — it changes what an Echo Show displays |
197
244
  | `PushClient` | handshake live (HTTP/2, 200, multipart boundary). the stream is then closed within ~1 s because the test session shares its registration with a running `alexa_media` (one stream per registration, see *Known limitations*); event parsing is unit tested only |
198
245
  | `probe_local`, `is_reachable` | live (two Echo models answer, a smart TV of another brand returns None) |
199
246
 
@@ -226,6 +273,20 @@ HTTP.
226
273
  sends `PUSH_NOTIFICATION_CHANGE`).
227
274
  - `devices-v2` no longer reports MAC addresses or battery levels for most
228
275
  devices; the MAC comes from GraphQL and is missing for apps and groups.
276
+ - **Communication preferences** come from a service that fails for some
277
+ accounts (HTTP 503 on the test account). The call is not retried and raises
278
+ `AmazonEchoRateLimitError`; treat it as "not available for this device".
279
+ - **Guard** is looked up once per client: an account that gets Guard later is
280
+ noticed by a new client. The free version of Guard was retired by Amazon in
281
+ most countries; the code follows `alexapy` and could not be run.
282
+ - **Smart-home state** is what Amazon last heard from the device's own cloud.
283
+ A value Amazon cannot read is None, and `reachable` is False for a device its
284
+ cloud reports offline.
285
+ - **Locks.** Amazon offers `unlock` only for some locks; check
286
+ `endpoint.supports("lock", "unlock")`.
287
+ - **Deleting voice history is not implemented.** The only endpoint the existing
288
+ clients use for it, `/api/activities`, answers 404 since Amazon moved the
289
+ history to the privacy hub.
229
290
  - Amazon can change or remove any of this without notice.
230
291
 
231
292
  ## Development
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "python-amazon-echo"
7
- version = "0.1.1"
7
+ version = "0.2.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"
@@ -20,6 +20,8 @@ from .models import (
20
20
  BluetoothDevice,
21
21
  Device,
22
22
  EchoList,
23
+ Endpoint,
24
+ Guard,
23
25
  ListItem,
24
26
  MediaState,
25
27
  Notification,
@@ -28,7 +30,7 @@ from .models import (
28
30
  )
29
31
  from .push import PushClient, PushEvent
30
32
 
31
- __version__ = "0.1.1"
33
+ __version__ = "0.2.0"
32
34
 
33
35
  __all__ = [
34
36
  "Account",
@@ -46,6 +48,8 @@ __all__ = [
46
48
  "Credentials",
47
49
  "Device",
48
50
  "EchoList",
51
+ "Endpoint",
52
+ "Guard",
49
53
  "ListItem",
50
54
  "LocalInfo",
51
55
  "MediaState",