python-amazon-echo 0.1.0__py3-none-any.whl

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.
amazon_echo/push.py ADDED
@@ -0,0 +1,298 @@
1
+ """HTTP/2 push channel: state changes arrive without polling.
2
+
3
+ The Alexa app keeps one long-lived HTTP/2 request open (the AVS "downchannel")
4
+ on which Amazon writes a multipart stream. Every part is a JSON directive; the
5
+ interesting ones carry ``renderingUpdates`` with a command such as
6
+ ``PUSH_VOLUME_CHANGE`` and its payload.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import asyncio
12
+ from collections.abc import Callable
13
+ import contextlib
14
+ from dataclasses import dataclass, field
15
+ from email.message import EmailMessage
16
+ import json
17
+ import logging
18
+ import time
19
+ from typing import Any
20
+
21
+ import httpx
22
+
23
+ from .client import AmazonEchoClient
24
+ from .const import AVS_HOST, DEVICE_CAPABILITIES, PUSH_HOST, PUSH_VERSION
25
+ from .exceptions import (
26
+ AmazonEchoAuthenticationError,
27
+ AmazonEchoError,
28
+ AmazonEchoResponseError,
29
+ )
30
+
31
+ _LOGGER = logging.getLogger(__name__)
32
+
33
+ _PING_INTERVAL = 280.0
34
+ _BACKOFF_BASE = 5.0
35
+ _BACKOFF_MAX = 600.0
36
+ _STABLE_AFTER = 60.0 # a stream that lived this long resets the back-off
37
+ _MAX_BUFFER = 512 * 1024
38
+
39
+
40
+ @dataclass(slots=True)
41
+ class PushEvent:
42
+ """One push message."""
43
+
44
+ command: str
45
+ device_serial: str | None = None
46
+ device_type: str | None = None
47
+ payload: dict[str, Any] = field(default_factory=dict)
48
+
49
+
50
+ def _loads(value: Any) -> dict[str, Any]:
51
+ """Return ``value`` as a dict, decoding it when it is a JSON string."""
52
+ if isinstance(value, str):
53
+ try:
54
+ value = json.loads(value)
55
+ except ValueError:
56
+ return {}
57
+ return value if isinstance(value, dict) else {}
58
+
59
+
60
+ def parse_boundary(content_type: str) -> bytes:
61
+ """Return the multipart delimiter (``--boundary``) of a Content-Type."""
62
+ message = EmailMessage()
63
+ message["Content-Type"] = content_type
64
+ boundary = message.get_boundary()
65
+ if not boundary:
66
+ raise AmazonEchoResponseError(200, f"No multipart boundary: {content_type}")
67
+ return f"--{boundary}".encode()
68
+
69
+
70
+ class StreamParser:
71
+ """Split the multipart byte stream into JSON documents."""
72
+
73
+ def __init__(self, delimiter: bytes) -> None:
74
+ """Initialize the parser with the ``--boundary`` delimiter."""
75
+ self._delimiter = delimiter
76
+ self._buffer = bytearray()
77
+
78
+ def feed(self, chunk: bytes) -> list[dict[str, Any]]:
79
+ """Add received bytes and return the documents that are now complete."""
80
+ self._buffer.extend(chunk)
81
+ if len(self._buffer) > _MAX_BUFFER:
82
+ self._buffer.clear()
83
+ raise AmazonEchoResponseError(200, "Push buffer overflow")
84
+ documents = []
85
+ while (index := self._buffer.find(self._delimiter)) != -1:
86
+ part = bytes(self._buffer[:index])
87
+ del self._buffer[: index + len(self._delimiter)]
88
+ start, end = part.find(b"{"), part.rfind(b"}")
89
+ if start == -1 or end < start:
90
+ continue # preamble, heartbeat or headers only
91
+ try:
92
+ document = json.loads(part[start : end + 1])
93
+ except ValueError:
94
+ _LOGGER.debug("Unparsable push part (%d bytes)", len(part))
95
+ continue
96
+ if isinstance(document, dict):
97
+ documents.append(document)
98
+ return documents
99
+
100
+
101
+ def parse_events(document: dict[str, Any]) -> list[PushEvent]:
102
+ """Turn one directive into push events; nothing is dropped."""
103
+ directive = _loads(document.get("directive"))
104
+ payload = _loads(directive.get("payload"))
105
+ updates = payload.get("renderingUpdates")
106
+ if not isinstance(updates, list):
107
+ header = _loads(directive.get("header"))
108
+ name = ".".join(
109
+ str(header[key]) for key in ("namespace", "name") if header.get(key)
110
+ )
111
+ return [PushEvent(command=name or "UNKNOWN", payload=payload)]
112
+ events = []
113
+ for update in updates:
114
+ if not isinstance(update, dict):
115
+ continue
116
+ metadata = _loads(update.get("resourceMetadata"))
117
+ body = _loads(metadata.get("payload"))
118
+ command = (
119
+ metadata.get("command")
120
+ or update.get("resourceId")
121
+ or update.get("route")
122
+ or "UNKNOWN"
123
+ )
124
+ doppler = _loads(body.get("dopplerId"))
125
+ serial = doppler.get("deviceSerialNumber")
126
+ device_type = doppler.get("deviceType")
127
+ if not serial:
128
+ # activity records: key.entryId = "<epoch ms>#<deviceType>#<serial>"
129
+ entry = str(_loads(body.get("key")).get("entryId") or "").split("#")
130
+ if len(entry) >= 3:
131
+ device_type, serial = entry[-2], entry[-1]
132
+ events.append(
133
+ PushEvent(
134
+ command=str(command),
135
+ device_serial=serial or None,
136
+ device_type=device_type or None,
137
+ payload=body or metadata or update,
138
+ )
139
+ )
140
+ return events
141
+
142
+
143
+ class PushClient:
144
+ """Long-lived HTTP/2 connection that delivers :class:`PushEvent`.
145
+
146
+ Args:
147
+ client: The API client whose session is used.
148
+ on_event: Called for every push message.
149
+ on_state: Called with True/False when the stream opens/closes.
150
+
151
+ """
152
+
153
+ def __init__(
154
+ self,
155
+ client: AmazonEchoClient,
156
+ on_event: Callable[[PushEvent], None],
157
+ *,
158
+ on_state: Callable[[bool], None] | None = None,
159
+ ) -> None:
160
+ """Initialize the push client."""
161
+ self._client = client
162
+ self._on_event = on_event
163
+ self._on_state = on_state
164
+ self._task: asyncio.Task[None] | None = None
165
+ self._http: httpx.AsyncClient | None = None
166
+ self._registered = False
167
+ self.connected = False
168
+
169
+ async def start(self) -> None:
170
+ """Start the background task (it reconnects on its own)."""
171
+ if self._task is None or self._task.done():
172
+ self._task = asyncio.create_task(self._run(), name="amazon_echo-push")
173
+
174
+ async def stop(self) -> None:
175
+ """Stop the background task and close the connection."""
176
+ task, self._task = self._task, None
177
+ if task is not None:
178
+ task.cancel()
179
+ with contextlib.suppress(asyncio.CancelledError):
180
+ await task
181
+ http, self._http = self._http, None
182
+ if http is not None:
183
+ await http.aclose()
184
+ self._set_connected(connected=False)
185
+
186
+ def _set_connected(self, *, connected: bool) -> None:
187
+ if self.connected == connected:
188
+ return
189
+ self.connected = connected
190
+ if self._on_state is not None:
191
+ try:
192
+ self._on_state(connected)
193
+ except Exception:
194
+ _LOGGER.exception("Push state callback failed")
195
+
196
+ async def _run(self) -> None:
197
+ """Keep the stream open, backing off 5·2ⁿ s (≤ 600 s) between tries."""
198
+ attempt = 0
199
+ while True:
200
+ started = time.monotonic()
201
+ try:
202
+ await self._stream()
203
+ _LOGGER.debug("Push stream closed by Amazon")
204
+ except AmazonEchoError as err:
205
+ _LOGGER.debug("Push stream failed: %s", err)
206
+ except Exception as err: # noqa: BLE001 - the task must survive anything
207
+ _LOGGER.debug("Push connection lost: %r", err)
208
+ finally:
209
+ self._set_connected(connected=False)
210
+ if time.monotonic() - started >= _STABLE_AFTER:
211
+ attempt = 0
212
+ await asyncio.sleep(min(_BACKOFF_BASE * 2**attempt, _BACKOFF_MAX))
213
+ attempt += 1
214
+
215
+ async def _base_url(self) -> str:
216
+ urls = await self._client.get_service_urls()
217
+ return urls.get("bobDispatchUrl") or "https://" + PUSH_HOST.format(
218
+ region=self._client.home_region.lower()
219
+ )
220
+
221
+ async def _bearer(self) -> dict[str, str]:
222
+ return {
223
+ "Authorization": f"Bearer {await self._client.async_get_access_token()}"
224
+ }
225
+
226
+ async def _register_capabilities(self, http: httpx.AsyncClient) -> None:
227
+ """Declare the app's AVS capabilities; without them nothing is pushed.
228
+
229
+ Sessions imported from ``alexa_media`` share that integration's
230
+ registration, which already declared them, so they are left alone.
231
+ """
232
+ if self._registered or self._client.credentials.source == "alexa_media":
233
+ return
234
+ response = await http.put(
235
+ f"https://{AVS_HOST}/v1/devices/@self/capabilities",
236
+ json=DEVICE_CAPABILITIES,
237
+ headers=await self._bearer(),
238
+ )
239
+ self._check(response.status_code, "capabilities")
240
+ self._registered = True
241
+
242
+ def _check(self, status: int, what: str) -> None:
243
+ if status in (401, 403):
244
+ # make the next attempt fetch a new token
245
+ self._client.credentials.access_token_expires = 0.0
246
+ raise AmazonEchoAuthenticationError(f"Push {what} rejected (HTTP {status})")
247
+ if status >= 400:
248
+ raise AmazonEchoResponseError(status, f"push {what}")
249
+
250
+ async def _stream(self) -> None:
251
+ """Open the downchannel once and process it until it ends."""
252
+ if self._http is None:
253
+ # building the TLS context reads the CA bundle from disk
254
+ self._http = await asyncio.get_running_loop().run_in_executor(
255
+ None, lambda: httpx.AsyncClient(http2=True, timeout=httpx.Timeout(30.0))
256
+ )
257
+ http = self._http
258
+ base = await self._base_url()
259
+ await self._register_capabilities(http)
260
+ async with http.stream(
261
+ "GET",
262
+ f"{base}/{PUSH_VERSION}/directives",
263
+ headers={**await self._bearer(), "Accept": "multipart/related"},
264
+ timeout=httpx.Timeout(30.0, read=None),
265
+ ) as response:
266
+ self._check(response.status_code, "stream")
267
+ parser = StreamParser(
268
+ parse_boundary(response.headers.get("content-type", ""))
269
+ )
270
+ self._set_connected(connected=True)
271
+ ping = asyncio.create_task(self._ping(http, base))
272
+ read = asyncio.create_task(self._read(response, parser))
273
+ try:
274
+ done, _ = await asyncio.wait(
275
+ {ping, read}, return_when=asyncio.FIRST_COMPLETED
276
+ )
277
+ finally:
278
+ for task in (ping, read):
279
+ task.cancel()
280
+ await asyncio.gather(ping, read, return_exceptions=True)
281
+ for task in done:
282
+ task.result()
283
+
284
+ async def _read(self, response: httpx.Response, parser: StreamParser) -> None:
285
+ async for chunk in response.aiter_bytes():
286
+ for document in parser.feed(chunk):
287
+ for event in parse_events(document):
288
+ try:
289
+ self._on_event(event)
290
+ except Exception:
291
+ _LOGGER.exception("Push event callback failed")
292
+
293
+ async def _ping(self, http: httpx.AsyncClient, base: str) -> None:
294
+ """Keep the connection alive; a failing ping ends the stream."""
295
+ while True:
296
+ await asyncio.sleep(_PING_INTERVAL)
297
+ response = await http.get(f"{base}/ping", headers=await self._bearer())
298
+ self._check(response.status_code, "ping")
amazon_echo/py.typed ADDED
File without changes
@@ -0,0 +1,268 @@
1
+ Metadata-Version: 2.5
2
+ Name: python-amazon-echo
3
+ Version: 0.1.0
4
+ Summary: Async Python client for Amazon Echo / Alexa devices: state, settings, media, notifications, lists, HTTP/2 push and LAN discovery
5
+ Project-URL: Homepage, https://github.com/hudsonbrendon/python-amazon-echo
6
+ Project-URL: Repository, https://github.com/hudsonbrendon/python-amazon-echo
7
+ Project-URL: Issues, https://github.com/hudsonbrendon/python-amazon-echo/issues
8
+ Project-URL: Changelog, https://github.com/hudsonbrendon/python-amazon-echo/blob/main/CHANGELOG.md
9
+ Author-email: Hudson Brendon <contato.hudsonbrendon@gmail.com>
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: aiohttp,alexa,amazon,async,echo,fire-tv,home-assistant
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Framework :: AsyncIO
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.14
18
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
19
+ Classifier: Typing :: Typed
20
+ Requires-Python: >=3.14
21
+ Requires-Dist: aiohttp>=3.10
22
+ Requires-Dist: httpx[http2]>=0.27
23
+ Description-Content-Type: text/markdown
24
+
25
+ # python-amazon-echo
26
+
27
+ [![Tests](https://github.com/hudsonbrendon/python-amazon-echo/actions/workflows/tests.yml/badge.svg)](https://github.com/hudsonbrendon/python-amazon-echo/actions/workflows/tests.yml)
28
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
29
+
30
+ Async Python client for Amazon Echo / Alexa devices: device inventory, state,
31
+ settings, media, text-to-speech, alarms/timers/reminders, lists, voice history,
32
+ an HTTP/2 push channel and LAN discovery. It is the library behind the
33
+ `amazon_echo` Home Assistant integration.
34
+
35
+ It was written from a reverse-engineering pass over the Alexa app
36
+ (`com.amazon.dee.app` 2.2.730155.0), the Alexa web API and what an Echo exposes
37
+ on the local network. It is not affiliated with Amazon.
38
+
39
+ ## Features
40
+
41
+ - **No password storage.** You log in in your own browser (passkeys, 2FA and
42
+ captchas just work) and paste the final URL; the library keeps a refresh token
43
+ and cookies. A session of the `alexa_media` integration can be imported too.
44
+ - **Self-healing session.** A 401/403 triggers one cookie exchange with the
45
+ refresh token and a retry; 429/503 are retried with a short back-off; every
46
+ change of tokens or cookies is reported through `on_credentials_update`.
47
+ - **Inventory and state in bulk.** Devices merged with the GraphQL endpoints
48
+ (MAC, model, endpoint id), and one call each for volumes, do-not-disturb,
49
+ Bluetooth, notifications, alarm volumes, wake words, ascending alarms and the
50
+ GraphQL state (temperature, reachability, Fire TV remote battery, ambient mode).
51
+ - **Settings nobody else exposes.** Equalizer, request sounds (earcons), alarm
52
+ volume, default alarm sound, ascending alarm, wake word, AUX direction, whisper
53
+ mode, adaptive volume and any per-device setting key (speaking rate, time zone,
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.
58
+ - **Lists.** Shopping, to-do and custom lists with full item CRUD.
59
+ - **Voice history.**
60
+ - **Push.** One HTTP/2 stream delivers volume, playback, do-not-disturb,
61
+ Bluetooth, notification, list and activity events; unknown events are passed
62
+ through, never dropped.
63
+ - **LAN.** Identify an Echo by IP (name, model, multi-room groups, active Spotify
64
+ user) and check that it is alive, without the cloud.
65
+ - Fully typed (`py.typed`), `aiohttp` with an injectable session, `httpx[http2]`
66
+ for push.
67
+
68
+ ## Installation
69
+
70
+ ```bash
71
+ pip install python-amazon-echo
72
+ ```
73
+
74
+ Python 3.14 or newer.
75
+
76
+ ## Quick start
77
+
78
+ ```python
79
+ import asyncio
80
+ import json
81
+ from pathlib import Path
82
+
83
+ from amazon_echo import AmazonEchoClient, Credentials
84
+
85
+ PATH = Path("credentials.json")
86
+
87
+
88
+ def save(credentials: Credentials) -> None:
89
+ PATH.write_text(json.dumps(credentials.to_dict()))
90
+
91
+
92
+ async def main() -> None:
93
+ credentials = Credentials.from_dict(json.loads(PATH.read_text()))
94
+ async with AmazonEchoClient(credentials, on_credentials_update=save) as client:
95
+ devices = await client.get_devices()
96
+ volumes = await client.get_volumes()
97
+ for device in devices:
98
+ print(device.name, device.model, device.online, volumes.get(device.serial))
99
+
100
+ echo = next(d for d in devices if d.family == "ECHO")
101
+ await client.set_volume(echo, 30)
102
+ await client.speak(echo, "Hello from Python")
103
+
104
+
105
+ asyncio.run(main())
106
+ ```
107
+
108
+ Push events:
109
+
110
+ ```python
111
+ from amazon_echo import PushClient, PushEvent
112
+
113
+
114
+ def on_event(event: PushEvent) -> None:
115
+ print(event.command, event.device_serial, event.payload)
116
+
117
+
118
+ push = PushClient(client, on_event, on_state=lambda up: print("push up:", up))
119
+ await push.start() # background task, reconnects with back-off 5·2ⁿ s (≤ 600 s)
120
+ ...
121
+ await push.stop()
122
+ ```
123
+
124
+ LAN:
125
+
126
+ ```python
127
+ from amazon_echo import is_reachable, probe_local
128
+
129
+ info = await probe_local("192.168.1.50") # None if it is not an Amazon device
130
+ print(info.name, info.model, info.groups, info.spotify_user)
131
+ print(await is_reachable("192.168.1.50"))
132
+ ```
133
+
134
+ ## Logging in with your own browser
135
+
136
+ ```python
137
+ from amazon_echo import build_authorize_url, register_device
138
+
139
+ request = build_authorize_url(language="en-US")
140
+ print(request.url) # 1. open it and log in to Amazon
141
+ redirect = input("Paste the final URL: ") # 2. see below
142
+ credentials = await register_device(request, redirect)
143
+ ```
144
+
145
+ 1. Open `request.url` in any browser and log in as usual (password, passkey,
146
+ 2FA, captcha — whatever Amazon asks for). The login always starts on
147
+ amazon.com, also for accounts of other marketplaces.
148
+ 2. When the login is done the browser lands on a blank or "page not found" page
149
+ whose address starts with `https://www.amazon.com/ap/maplanding?` and contains
150
+ `openid.oa2.authorization_code=…`. That is expected. Copy the whole address.
151
+ 3. Pass it to `register_device`. The one-time code is exchanged for a device
152
+ registration ("Amazon Echo for Home Assistant" shows up in your Amazon
153
+ account under *Manage your content and devices*), the account's own
154
+ marketplace is discovered and cookies for it are fetched.
155
+
156
+ Keep the same `AuthorizeRequest` between steps 1 and 3 (it carries the PKCE
157
+ verifier), and persist `credentials.to_dict()`.
158
+
159
+ The command line does the same: `amazon-echo login`.
160
+
161
+ To reuse a session of the `alexa_media` integration instead:
162
+
163
+ ```python
164
+ credentials = Credentials.from_alexa_media(entry_data, cookies)
165
+ # entry_data: the `data` of the alexa_media config entry
166
+ # cookies: the "cookies" list of .storage/alexa_media.<email>.cookies
167
+ ```
168
+
169
+ Such a session shares one device registration with `alexa_media`. Everything
170
+ works except push while both run (see *Known limitations*).
171
+
172
+ ## Command line
173
+
174
+ ```bash
175
+ amazon-echo login
176
+ amazon-echo devices # also: account, states, volumes, dnd, bluetooth,
177
+ # notifications, routines, lists, history, providers
178
+ amazon-echo push # print push events
179
+ amazon-echo probe 192.168.1.50
180
+ ```
181
+
182
+ Credentials are read from `~/.config/amazon-echo/credentials.json`
183
+ (`--credentials` to change).
184
+
185
+ ## Verification
186
+
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.
189
+
190
+ - **live read** — called against Amazon through this library, answer parsed.
191
+ - **no-op write** — the value just read was written back to one Echo Plus and
192
+ read again; Amazon accepted the request.
193
+ - **ported** — implemented from the app / existing open-source clients and unit
194
+ tested only. Not replayed live (audible or disruptive).
195
+
196
+ | API | Status |
197
+ |---|---|
198
+ | `request`, 429/503 retry, non-JSON detection | live read |
199
+ | `async_get_access_token` (`auth/token`) | live (token refreshed) |
200
+ | Cookie exchange on 401/403 (`auth/token`, `auth_cookies`) | ported — never triggered live |
201
+ | `build_authorize_url`, `register_device` | ported (the authorize URL answers 302 as expected; no registration was made) |
202
+ | `get_account`, `get_devices`, `get_routines`, `get_music_providers`, `get_service_urls` | live read |
203
+ | `get_dnd`, `get_volumes`, `get_bluetooth`, `get_notifications`, `get_alarm_volumes`, `get_wake_words`, `get_ascending_alarms`, `get_endpoint_states` | live read |
204
+ | `get_media` | live read (idle player only) |
205
+ | `get_wifi`, `get_equalizer`, `get_earcons`, `get_aux`, `get_setting`, `get_available_wake_words`, `get_alarm_sounds`, `get_default_alarm_sound` | live read |
206
+ | `get_whisper_mode`, `get_adaptive_volume` | live read |
207
+ | `set_whisper_mode`, `set_adaptive_volume` | no-op write during the reverse engineering (same request), not replayed by the library |
208
+ | `set_dnd`, `set_equalizer`, `set_earcons`, `set_alarm_volume`, `set_ascending_alarm`, `set_default_alarm_sound`, `set_setting` | no-op write |
209
+ | `set_aux_direction` | no-op write accepted; the body field name is unconfirmed |
210
+ | `set_volume` (sequence pipeline) | no-op write |
211
+ | `create_reminder`, `delete_notification` | live (a reminder 320 days ahead was created and deleted) |
212
+ | `create_alarm` | ported |
213
+ | `create_timer` | ported — body inferred from field names in the app, never sent |
214
+ | `set_wake_word` | ported |
215
+ | `speak`, `announce`, `text_command`, `play_sound`, `play_music`, `launch_skill`, `run_routine`, `stop` | ported |
216
+ | `media_command`, `bluetooth_connect`, `bluetooth_disconnect`, `reboot` | ported |
217
+ | `get_lists`, `get_list_items` | live read |
218
+ | `add_list_item`, `update_list_item`, `delete_list_item` | ported |
219
+ | `get_voice_history` | live read |
220
+ | `call_feature` | ported |
221
+ | `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
+ | `probe_local`, `is_reachable` | live (two Echo models answer, a smart TV of another brand returns None) |
223
+
224
+ ## Known limitations
225
+
226
+ - **An Echo has no local control API.** On the LAN it only answers the Spotify
227
+ Connect zeroconf endpoint (TCP 4070), advertises itself as a Matter controller
228
+ and Thread border router, and accepts TCP on its multi-room audio port (55442).
229
+ "Local" in this library therefore means discovery, name/model/group lookup and
230
+ liveness. Every command and every other piece of state goes through Amazon's
231
+ cloud; push only removes the polling.
232
+ - **Push with an imported `alexa_media` session.** Amazon keeps one push stream per
233
+ app registration and the newest connection wins. Verified on 2026-11-15 with
234
+ `alexa_media` debug logging on: opening our stream made `alexa_media` log
235
+ `HTTP2 Connection Closed`, it reconnected at once, and that closed ours about a
236
+ second later. So do not run `PushClient` on an imported session while
237
+ `alexa_media` is running; poll instead, or sign in with the browser flow to get
238
+ an own registration. `PushClient` does not re-declare AVS capabilities for
239
+ imported sessions.
240
+ - **Alarm and reminder times** are read by Amazon in the Echo's own time zone and
241
+ the API takes no zone. Aware datetimes are converted to the system time zone;
242
+ pass a naive datetime in the Echo's local time if the host lives elsewhere.
243
+ - **Alarms have no label** in Amazon's API; `create_alarm(label=…)` is accepted
244
+ and ignored.
245
+ - **`create_timer` is unverified** (see the table). Use
246
+ `text_command(device, "set a timer for 5 minutes")` if it is rejected.
247
+ - **Voice history** comes 10 records per call; at most 50 are fetched.
248
+ - **Lists** return the first 100 items.
249
+ - **`get_notifications`** is a large, rate-limited answer; call it sparingly (push
250
+ sends `PUSH_NOTIFICATION_CHANGE`).
251
+ - `devices-v2` no longer reports MAC addresses or battery levels for most
252
+ devices; the MAC comes from GraphQL and is missing for apps and groups.
253
+ - Amazon can change or remove any of this without notice.
254
+
255
+ ## Development
256
+
257
+ ```bash
258
+ uv sync
259
+ uv run ruff check . && uv run ruff format --check .
260
+ uv run mypy src
261
+ uv run pytest
262
+ ```
263
+
264
+ Test fixtures are hand-written; no real account data is in this repository.
265
+
266
+ ## License
267
+
268
+ MIT
@@ -0,0 +1,15 @@
1
+ amazon_echo/__init__.py,sha256=JWwYSTgTKyuXumG72MM7oZvzlH9eBQzuezSObrrEOHE,1383
2
+ amazon_echo/__main__.py,sha256=1Hhd7w2cW5Z9jmwO1OThhcj6gbTLVqAQu5fAMqijJ_0,4325
3
+ amazon_echo/auth.py,sha256=O5SAtY5Wf76-LtFOkHJvrzlNoZdprgJsx5-3crEPUGQ,14417
4
+ amazon_echo/client.py,sha256=hvAn56wNNp_NYne8cIc1QVEDEKZVzGs5ZeyDM7uQZxw,62402
5
+ amazon_echo/const.py,sha256=Gvu7iQI4hnGIpSbWDOFXvIb78wxtWmQVOzSWCzXDkTU,9128
6
+ amazon_echo/exceptions.py,sha256=7ETH4C2sKbKEJWnJ30ygAO0a_GiD5PWmDHJCSVTedAU,1120
7
+ amazon_echo/local.py,sha256=KHwwgC2-MzFZ0wBaxXRuotyr7-zrrenzfM0P3BEMRvE,3080
8
+ amazon_echo/models.py,sha256=2RV4rN4G2cNXAbIKDwEWxVgVdJxl98mlHjs6pmHWV6k,3967
9
+ amazon_echo/push.py,sha256=KMcHeDLgRxEjCQpTybiJUAUNTFTxlDMpTVPDv0ZYAzE,11206
10
+ amazon_echo/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
11
+ python_amazon_echo-0.1.0.dist-info/METADATA,sha256=S5766fT2yrGfj73Ci08RhP8rxbtbp77o0RPMnCeUrLc,12236
12
+ python_amazon_echo-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
13
+ python_amazon_echo-0.1.0.dist-info/entry_points.txt,sha256=rbZJ8BI8kkiDTV9cKk6acbHuyAm2xNYfpDBXQNw8Yb8,58
14
+ python_amazon_echo-0.1.0.dist-info/licenses/LICENSE,sha256=4Zgd3fbLJqWSkwKA-hh1rNN6DC9tNQ3rWLX93fingOw,1071
15
+ python_amazon_echo-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ amazon-echo = amazon_echo.__main__:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Hudson Brendon
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.