python-amazon-echo 0.3.0__py3-none-any.whl → 0.3.2__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/__init__.py CHANGED
@@ -30,7 +30,7 @@ from .models import (
30
30
  )
31
31
  from .push import PushClient, PushEvent
32
32
 
33
- __version__ = "0.3.0"
33
+ __version__ = "0.3.2"
34
34
 
35
35
  __all__ = [
36
36
  "Account",
amazon_echo/client.py CHANGED
@@ -67,11 +67,14 @@ from .models import (
67
67
  Routine,
68
68
  VoiceRecord,
69
69
  )
70
+ from .phrases import timer_request
70
71
 
71
72
  _LOGGER = logging.getLogger(__name__)
72
73
 
73
74
  _TIMEOUT = aiohttp.ClientTimeout(total=30)
74
75
  _RETRY_DELAYS = (1.0, 3.0) # back-off before the 2nd and 3rd attempt on 429/503
76
+ _TIMER_POLLS = 8
77
+ _TIMER_POLL_SECONDS = 3.0
75
78
  _REAUTH_COOLDOWN = 60.0 # a 401/403 this soon after a cookie exchange is final
76
79
  _TOKEN_MARGIN = 60.0
77
80
  _HISTORY_CSRF_TTL = 12 * 3600
@@ -124,6 +127,26 @@ def _local(when: datetime) -> datetime:
124
127
  return when.astimezone().replace(tzinfo=None) if when.tzinfo else when
125
128
 
126
129
 
130
+ def _from_original(item: dict[str, Any]) -> datetime | None:
131
+ """Local ``originalDate`` + ``originalTime`` (music alarms carry only these).
132
+
133
+ Same time zone assumption as :func:`_local`; a repeating alarm whose first
134
+ date is past moves to its next ring.
135
+ """
136
+ date, clock = item.get("originalDate"), item.get("originalTime")
137
+ if not date or not clock:
138
+ return None
139
+ try:
140
+ when = datetime.fromisoformat(f"{date}T{str(clock)[:8]}").astimezone()
141
+ if item.get("recurringPattern") and when < datetime.now().astimezone():
142
+ # _next_ring works on local wall-clock time
143
+ ring = _next_ring(item, datetime.now()) # noqa: DTZ005
144
+ when = datetime.fromisoformat(ring).astimezone()
145
+ except ValueError:
146
+ return None
147
+ return when
148
+
149
+
127
150
  def parse_notification(item: dict[str, Any]) -> Notification:
128
151
  """Build a :class:`Notification` from an ``/api/notifications`` item."""
129
152
  kind = NOTIFICATION_KINDS.get(item.get("type") or "", "")
@@ -131,7 +154,11 @@ def parse_notification(item: dict[str, Any]) -> Notification:
131
154
  if item.get("musicAlarmId") and kind == "alarm":
132
155
  kind = "music_alarm"
133
156
  remaining = item.get("remainingTime") or 0
134
- when = _from_ms(item.get("triggerTime")) or _from_ms(item.get("alarmTime"))
157
+ when = (
158
+ _from_ms(item.get("triggerTime"))
159
+ or _from_ms(item.get("alarmTime"))
160
+ or (_from_original(item) if kind in ("alarm", "music_alarm") else None)
161
+ )
135
162
  return Notification(
136
163
  id=item["id"],
137
164
  kind=kind,
@@ -1676,30 +1703,45 @@ class AmazonEchoClient:
1676
1703
  raise AmazonEchoResponseError(200, "No reminder in the answer")
1677
1704
 
1678
1705
  async def create_timer(
1679
- self, device: Device, duration: timedelta, *, label: str | None = None
1706
+ self,
1707
+ device: Device,
1708
+ duration: timedelta,
1709
+ *,
1710
+ label: str | None = None,
1711
+ locale: str | None = None,
1680
1712
  ) -> Notification:
1681
- """Start a timer on ``device``.
1713
+ """Start a timer on ``device``; Alexa confirms it out loud.
1714
+
1715
+ Amazon has no API for this: the timers API of the app starts the timer
1716
+ on the app's own registration, not on an Echo. What works is a typed
1717
+ request with the duration in words (see :mod:`amazon_echo.phrases`),
1718
+ available for Portuguese and English.
1719
+
1720
+ Args:
1721
+ device: The Echo that will run the timer.
1722
+ duration: More than zero and less than 24 hours.
1723
+ label: Optional name of the timer.
1724
+ locale: Locale of the device; read from Amazon when omitted.
1725
+
1726
+ Raises:
1727
+ AmazonEchoNotSupportedError: No phrase for the device's language.
1728
+ AmazonEchoResponseError: Alexa did not start the timer.
1729
+ ValueError: The duration is out of range.
1682
1730
 
1683
- The request body follows the field names found in the Alexa app
1684
- (``/v1/alerts/timers``); it has not been replayed against Amazon.
1685
1731
  """
1686
- seconds = int(duration.total_seconds())
1687
- if seconds <= 0:
1688
- raise ValueError("The timer duration must be positive")
1732
+ if locale is None:
1733
+ preferences = await self.get_device_preferences()
1734
+ locale = (preferences.get(device.serial) or {}).get("locale") or "en-US"
1735
+ request = timer_request(duration, locale, label=label)
1689
1736
  known = {item.id for item in await self.get_notifications()}
1690
- body: dict[str, Any] = {
1691
- "duration": f"PT{seconds}S",
1692
- "creationBehavior": {"displayExperience": {"visibility": "VISIBLE"}},
1693
- "triggeringBehavior": {
1694
- "operation": {"type": "NOTIFY_ONLY"},
1695
- "notificationConfig": {"playAudible": True},
1696
- },
1697
- "endpointId": f"{device.serial}@{device.device_type}",
1698
- }
1699
- if label:
1700
- body["timerLabel"] = label
1701
- await self._alerts("POST", "timers", body)
1702
- return await self._find_new(device, "timer", known)
1737
+ await self.text_command(device, request)
1738
+ for _ in range(_TIMER_POLLS):
1739
+ await asyncio.sleep(_TIMER_POLL_SECONDS)
1740
+ try:
1741
+ return await self._find_new(device, "timer", known)
1742
+ except AmazonEchoResponseError:
1743
+ continue
1744
+ raise AmazonEchoResponseError(200, "The new timer did not show up")
1703
1745
 
1704
1746
  @staticmethod
1705
1747
  def _alarm_index(alarm: Notification) -> str:
amazon_echo/const.py CHANGED
@@ -4,7 +4,7 @@ from __future__ import annotations
4
4
 
5
5
  from typing import Any, Final
6
6
 
7
- VERSION: Final = "0.3.0"
7
+ VERSION: Final = "0.3.2"
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"
amazon_echo/phrases.py ADDED
@@ -0,0 +1,128 @@
1
+ """Spoken phrases for the things Alexa only accepts as a voice request.
2
+
3
+ Alexa has no API to start a timer on an Echo: the timers API of the app starts
4
+ it on the app's own registration. A typed request works, but only with the
5
+ numbers spelled out ("timer de dez minutos" starts one, "timer de 10 minutos"
6
+ makes Alexa ask for how long), so the duration is written in words here.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from datetime import timedelta
12
+
13
+ from .exceptions import AmazonEchoNotSupportedError
14
+
15
+ _PT_UNITS = [
16
+ "zero",
17
+ "um",
18
+ "dois",
19
+ "três",
20
+ "quatro",
21
+ "cinco",
22
+ "seis",
23
+ "sete",
24
+ "oito",
25
+ "nove",
26
+ "dez",
27
+ "onze",
28
+ "doze",
29
+ "treze",
30
+ "quatorze",
31
+ "quinze",
32
+ "dezesseis",
33
+ "dezessete",
34
+ "dezoito",
35
+ "dezenove",
36
+ ]
37
+ _PT_TENS = {20: "vinte", 30: "trinta", 40: "quarenta", 50: "cinquenta"}
38
+ _EN_UNITS = [
39
+ "zero",
40
+ "one",
41
+ "two",
42
+ "three",
43
+ "four",
44
+ "five",
45
+ "six",
46
+ "seven",
47
+ "eight",
48
+ "nine",
49
+ "ten",
50
+ "eleven",
51
+ "twelve",
52
+ "thirteen",
53
+ "fourteen",
54
+ "fifteen",
55
+ "sixteen",
56
+ "seventeen",
57
+ "eighteen",
58
+ "nineteen",
59
+ ]
60
+ _EN_TENS = {20: "twenty", 30: "thirty", 40: "forty", 50: "fifty"}
61
+
62
+
63
+ def _pt(number: int, *, feminine: bool = False) -> str:
64
+ if number < 20:
65
+ word = _PT_UNITS[number]
66
+ return {"um": "uma", "dois": "duas"}.get(word, word) if feminine else word
67
+ tens, rest = number - number % 10, number % 10
68
+ return _PT_TENS[tens] + (f" e {_pt(rest, feminine=feminine)}" if rest else "")
69
+
70
+
71
+ def _en(number: int) -> str:
72
+ if number < 20:
73
+ return _EN_UNITS[number]
74
+ tens, rest = number - number % 10, number % 10
75
+ return _EN_TENS[tens] + (f"-{_EN_UNITS[rest]}" if rest else "")
76
+
77
+
78
+ def _parts(duration: timedelta) -> tuple[int, int, int]:
79
+ seconds = int(duration.total_seconds())
80
+ if not 0 < seconds < 24 * 3600:
81
+ raise ValueError("The timer duration must be between 1 second and 24 hours")
82
+ return seconds // 3600, seconds % 3600 // 60, seconds % 60
83
+
84
+
85
+ def timer_request(
86
+ duration: timedelta, language: str, *, label: str | None = None
87
+ ) -> str:
88
+ """Return the typed request that starts a timer of ``duration``.
89
+
90
+ Args:
91
+ duration: More than zero and less than 24 hours.
92
+ language: Locale of the device, e.g. ``pt-BR`` or ``en-US``.
93
+ label: Optional name of the timer.
94
+
95
+ Raises:
96
+ AmazonEchoNotSupportedError: No phrase for that language.
97
+ ValueError: The duration is out of range.
98
+
99
+ """
100
+ hours, minutes, seconds = _parts(duration)
101
+ code = language[:2].lower()
102
+ if code == "pt":
103
+ spoken = " e ".join(
104
+ f"{_pt(n, feminine=feminine)} {one if n == 1 else many}"
105
+ for n, one, many, feminine in (
106
+ (hours, "hora", "horas", True),
107
+ (minutes, "minuto", "minutos", False),
108
+ (seconds, "segundo", "segundos", False),
109
+ )
110
+ if n
111
+ )
112
+ return f"timer de {spoken}" + (f" chamado {label}" if label else "")
113
+ if code == "en":
114
+ spoken = " and ".join(
115
+ f"{_en(n)} {one if n == 1 else many}"
116
+ for n, one, many in (
117
+ (hours, "hour", "hours"),
118
+ (minutes, "minute", "minutes"),
119
+ (seconds, "second", "seconds"),
120
+ )
121
+ if n
122
+ )
123
+ return (
124
+ (f"set a {label} timer for {spoken}")
125
+ if label
126
+ else f"set a timer for {spoken}"
127
+ )
128
+ raise AmazonEchoNotSupportedError(f"No timer phrase for the language {language!r}")
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: python-amazon-echo
3
- Version: 0.3.0
3
+ Version: 0.3.2
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
@@ -243,10 +243,10 @@ with mocked HTTP.
243
243
  | `set_aux_direction` | no-op write accepted; the body field name is unconfirmed |
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
- | `create_alarm` | ported |
246
+ | `create_alarm` | verified live: a plain alarm earlier, and on 2026-11-16 a music alarm (`music=`, reusing a Spotify music alarm made by voice) created on an Echo Plus and deleted |
247
247
  | `create_alarm(music=…)` (music alarm that reuses the station of an existing one) | ported from Alexa Media Player's request, never sent |
248
248
  | `play_music(timer=…)` (stop after that many seconds) | ported from Alexa Media Player's payload, never sent |
249
- | `create_timer` | ported — body inferred from field names in the app, never sent |
249
+ | `create_timer` | verified live on an Echo Plus (pt-BR): a 12-minute timer, with and without a name, created and deleted. It is a typed request with the duration in words; English phrases are unit-tested only |
250
250
  | `set_wake_word` | ported |
251
251
  | `speak`, `announce`, `text_command`, `play_sound`, `play_music`, `launch_skill`, `run_routine`, `stop` | ported |
252
252
  | `media_command`, `bluetooth_connect`, `bluetooth_disconnect`, `reboot` | ported |
@@ -258,7 +258,7 @@ with mocked HTTP.
258
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 |
259
259
  | `parse_endpoint_update` (smart-home push) | ported, not replayed live — no push stream on the test session |
260
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 |
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 |
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 roughly nine out of ten of some 60 requests on 2026-11-16, on both the `.com` and the marketplace host, with cookies or a bearer token |
262
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 |
263
263
  | `get_device_preferences`, `get_kids_mode`, `get_children`, `get_kids_profile` | live read |
264
264
  | `set_kids_mode` | ported, not replayed live — it changes how a device behaves |
@@ -294,8 +294,11 @@ with mocked HTTP.
294
294
  - **Music alarms** can only reuse a station: `create_alarm(music=…)` takes a
295
295
  music alarm that already exists on the account (create one in the Alexa app
296
296
  first) and wakes with the same station. Amazon has no public search for one.
297
- - **`create_timer` is unverified** (see the table). Use
298
- `text_command(device, "set a timer for 5 minutes")` if it is rejected.
297
+ - **`create_timer`** speaks: Alexa has no API to start a timer on an Echo (the
298
+ app's timers API starts it on the app's own registration, which was observed
299
+ live), so the request is typed with the duration in words and Alexa confirms
300
+ it out loud. Portuguese and English only; other languages raise
301
+ `AmazonEchoNotSupportedError`.
299
302
  - **Voice history** comes 10 records per call; at most 50 are fetched.
300
303
  - **Lists** return the first 100 items.
301
304
  - **`get_notifications`** is a large, rate-limited answer; call it sparingly (push
@@ -1,16 +1,17 @@
1
- amazon_echo/__init__.py,sha256=qY8C7gE4GVFBxuYAtrbgmhhoWxM8EAFej8HRcc2LuNo,1437
1
+ amazon_echo/__init__.py,sha256=jDc5ixY_0MCZ0fIDZ-fir3K5XzULlUip7TLPDtK0FTc,1437
2
2
  amazon_echo/__main__.py,sha256=1Hhd7w2cW5Z9jmwO1OThhcj6gbTLVqAQu5fAMqijJ_0,4325
3
3
  amazon_echo/auth.py,sha256=O5SAtY5Wf76-LtFOkHJvrzlNoZdprgJsx5-3crEPUGQ,14417
4
- amazon_echo/client.py,sha256=7AP2eBJ6_E_y029m8LwSEcz9d0WT0MR5Gu-YSrpuLdA,80593
5
- amazon_echo/const.py,sha256=vOG2d3FC5ewenGSNrFwXi7-X0Vp4GrPejcVjp2YQWrg,11880
4
+ amazon_echo/client.py,sha256=cDgGYQV36XiopxVZI-Nfg_x-Qf9s85LB6pCKRBdXOAo,82176
5
+ amazon_echo/const.py,sha256=NTm8ck2pPGYinNETKFsyCMBEAvO3jMIJmxO6WLvDxWU,11880
6
6
  amazon_echo/endpoints.py,sha256=_6vXYWtwGIR_2IjVFJAXWP1vR6jwzIpZ4upkRctwBp8,7925
7
7
  amazon_echo/exceptions.py,sha256=7ETH4C2sKbKEJWnJ30ygAO0a_GiD5PWmDHJCSVTedAU,1120
8
8
  amazon_echo/local.py,sha256=KHwwgC2-MzFZ0wBaxXRuotyr7-zrrenzfM0P3BEMRvE,3080
9
9
  amazon_echo/models.py,sha256=ZKEHuiyG7hqRt5M8nufyf1nyaRZ2-l1WXlOCzG4UH7A,5258
10
+ amazon_echo/phrases.py,sha256=iqhqIK07XRTWmAwJ5jhzGPtqatvUz4nywCvJvCgwTK0,3579
10
11
  amazon_echo/push.py,sha256=KMcHeDLgRxEjCQpTybiJUAUNTFTxlDMpTVPDv0ZYAzE,11206
11
12
  amazon_echo/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
12
- python_amazon_echo-0.3.0.dist-info/METADATA,sha256=TFFdzx2CS4r1ZfO3jl7f-LFyeSZ4dxZarv0LibnZbls,17589
13
- python_amazon_echo-0.3.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
14
- python_amazon_echo-0.3.0.dist-info/entry_points.txt,sha256=rbZJ8BI8kkiDTV9cKk6acbHuyAm2xNYfpDBXQNw8Yb8,58
15
- python_amazon_echo-0.3.0.dist-info/licenses/LICENSE,sha256=4Zgd3fbLJqWSkwKA-hh1rNN6DC9tNQ3rWLX93fingOw,1071
16
- python_amazon_echo-0.3.0.dist-info/RECORD,,
13
+ python_amazon_echo-0.3.2.dist-info/METADATA,sha256=U6Vz3el21WGFpFXXgJnu84_hLiVIR-qLA7EMno4tnbc,18087
14
+ python_amazon_echo-0.3.2.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
15
+ python_amazon_echo-0.3.2.dist-info/entry_points.txt,sha256=rbZJ8BI8kkiDTV9cKk6acbHuyAm2xNYfpDBXQNw8Yb8,58
16
+ python_amazon_echo-0.3.2.dist-info/licenses/LICENSE,sha256=4Zgd3fbLJqWSkwKA-hh1rNN6DC9tNQ3rWLX93fingOw,1071
17
+ python_amazon_echo-0.3.2.dist-info/RECORD,,