simplepush 3.6.1__tar.gz → 3.7.1__tar.gz

{simplepush-3.6.1 → simplepush-3.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simplepush
-Version: 3.6.1
+Version: 3.7.1
 Summary: Python client for Simplepush (tasks, notifications, events, end-to-end encryption).
 Project-URL: Homepage, https://simplepu.sh
 Project-URL: Documentation, https://simplepu.sh/guide/python-sdk
@@ -113,8 +113,9 @@ form at once (by default each filled input arrives as an intermediate
 set); `reply=ReplyMode.STICKY` (or `"one-shot"` / `"one-time-per-user"`) shows
 recipients an in-thread reply composer (collect via `replies()`);
 `content_format=ContentFormat.MARKDOWN` renders a task's `content` as
-Markdown (notifications are always plain); `critical=True` sends an iOS
-Critical Alert.
+Markdown (notifications are always plain); `priority=` sets how loudly the
+push interrupts, 1 (minimal) to 5 (critical; sounds even on a muted phone),
+default 3, with `critical_volume=` (0 to 1) for level 5 on iOS.
 
 A task can have **subtasks** appended to its chain. A subtask inherits the
 parent's recipients and encryption (no target, no password); its `inputs()` /

{simplepush-3.6.1 → simplepush-3.7.1}/README.md

@@ -63,8 +63,9 @@ form at once (by default each filled input arrives as an intermediate
 set); `reply=ReplyMode.STICKY` (or `"one-shot"` / `"one-time-per-user"`) shows
 recipients an in-thread reply composer (collect via `replies()`);
 `content_format=ContentFormat.MARKDOWN` renders a task's `content` as
-Markdown (notifications are always plain); `critical=True` sends an iOS
-Critical Alert.
+Markdown (notifications are always plain); `priority=` sets how loudly the
+push interrupts, 1 (minimal) to 5 (critical; sounds even on a muted phone),
+default 3, with `critical_volume=` (0 to 1) for level 5 on iOS.
 
 A task can have **subtasks** appended to its chain. A subtask inherits the
 parent's recipients and encryption (no target, no password); its `inputs()` /

{simplepush-3.6.1 → simplepush-3.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "simplepush"
-version = "3.6.1"
+version = "3.7.1"
 description = "Python client for Simplepush (tasks, notifications, events, end-to-end encryption)."
 readme = "README.md"
 license = { file = "LICENSE" }

{simplepush-3.6.1 → simplepush-3.7.1}/src/simplepush/api.py

@@ -56,12 +56,33 @@ from .client import (
     Event, GroupCancelResult, InputEvent, Notification, NotificationGroup,
     NotificationGroupRecipient, RawEvents, Reply, Subtask, Submissions, Task,
     TaskGroup, TaskGroupRecipient,
-    _DownloadTransport, _FileBinder, _Hub,
+    _HTTP_TIMEOUT, _DownloadTransport, _FileBinder, _Hub,
 )
 
 
 # --- Wire serialization helpers ---
 
+def _priority_wire(priority, critical, critical_volume) -> dict:
+    """The `priority` / `criticalVolume` fields of a create request. `priority`
+    is 1 (minimal) to 5 (critical), absent = 3; the deprecated `critical` flag
+    means 5 when no priority is given. `critical_volume` (0 < v <= 1) is the
+    iOS critical alert volume and is only valid with level 5."""
+    level = priority if priority is not None else (5 if critical else None)
+    if level is not None and (not isinstance(level, int) or isinstance(level, bool) or not 1 <= level <= 5):
+        raise ValueError("priority must be an integer between 1 and 5")
+    if critical_volume is not None:
+        if level != 5:
+            raise ValueError("critical_volume applies to priority 5 only")
+        if not 0 < critical_volume <= 1:
+            raise ValueError("critical_volume must be greater than 0 and at most 1")
+    out: dict = {}
+    if level is not None:
+        out["priority"] = level
+    if critical_volume is not None:
+        out["criticalVolume"] = critical_volume
+    return out
+
+
 def _expires_at_wire(value) -> str:
     """Serialize a task deadline to wire ISO-8601. A naive datetime is
     rejected rather than guessed at — the server compares against UTC."""
@@ -547,7 +568,7 @@ class _BaseClient:
             method="GET",
         )
         try:
-            with urllib.request.urlopen(req) as resp:
+            with urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT) as resp:
                 info = json.loads(resp.read().decode("utf-8"))
         except urllib.error.HTTPError as e:
             raise ApiError(e.code, e.read().decode("utf-8")) from e
@@ -595,6 +616,8 @@ class _BaseClient:
         password: str | None = None,
         tag: str | None = None,
         critical: bool = False,
+        priority: int | None = None,
+        critical_volume: float | None = None,
         reply: ReplyMode | Literal["one-shot", "sticky", "one-time-per-user"] | None = None,
         content_format: ContentFormat | Literal["plain", "markdown"] | None = None,
         shared: bool = False,
@@ -667,7 +690,7 @@ class _BaseClient:
             links=links, files=files,
             auto_commit=auto_commit,
             password=password if password is not None else self._send_password(topic),
-            tag=tag, critical=critical, reply=reply,
+            tag=tag, critical=critical, priority=priority, critical_volume=critical_volume, reply=reply,
             content_format=content_format, shared=shared,
             expires_at=expires_at,
         )
@@ -687,6 +710,8 @@ class _BaseClient:
         password: str | None = None,
         tag: str | None = None,
         critical: bool = False,
+        priority: int | None = None,
+        critical_volume: float | None = None,
         shared: bool = False,
     ) -> "Notification | NotificationGroup":
         """Send a notification and return a handle to its event stream.
@@ -757,13 +782,13 @@ class _BaseClient:
             title=title, content=content, input=input,
             image=image, audio=audio, link=link,
             password=password if password is not None else self._send_password(topic),
-            tag=tag, critical=critical, shared=shared,
+            tag=tag, critical=critical, priority=priority, critical_volume=critical_volume, shared=shared,
         )
 
     def _create_task(self, *, topic=None, member=None, broadcast=False,
                      title=None, content=None, inputs=None, links=None,
                      files=None,
-                     auto_commit=False, password=None, tag=None, critical=False,
+                     auto_commit=False, password=None, tag=None, critical=False, priority=None, critical_volume=None,
                      reply=None, content_format=None, shared=False,
                      expires_at=None) -> "Task | TaskGroup":
         if not content and not inputs:
@@ -893,8 +918,7 @@ class _BaseClient:
             body["title"] = title
         if content is not None:
             body["content"] = content
-        if critical:
-            body["critical"] = critical
+        body.update(_priority_wire(priority, critical, critical_volume))
         if reply is not None:
             body["reply"] = reply.value if isinstance(reply, ReplyMode) else reply
         if content_format is not None:
@@ -971,7 +995,7 @@ class _BaseClient:
 
     def _create_notification(self, *, topic=None, member=None, broadcast=False,
                              title=None, content=None, input=None, image=None, audio=None,
-                             link=None, password=None, tag=None, critical=False,
+                             link=None, password=None, tag=None, critical=False, priority=None, critical_volume=None,
                              shared=False) -> "Notification | NotificationGroup":
         if not content and input is None:
             raise ValueError("Either content or an input must be provided")
@@ -1098,8 +1122,7 @@ class _BaseClient:
             payload["choiceInput"] = {"options": choice_options}
         elif action_defs is not None:
             payload["actionInput"] = {"actions": action_defs}
-        if critical:
-            payload["critical"] = critical
+        payload.update(_priority_wire(priority, critical, critical_volume))
         if encryption_dict is not None:
             payload["encryption"] = encryption_dict
         if shared:
@@ -1227,7 +1250,7 @@ class _BaseClient:
 
     def _build_subtask_data(self, send_key, *, title=None, content=None, inputs=None,
                             links=None, files=None,
-                            auto_commit=False, critical=False,
+                            auto_commit=False, critical=False, priority=None, critical_volume=None,
                             reply=None, content_format=None) -> "tuple[dict, list]":
         """Build the (encrypted) `data` dict of a subtask append plus the
         prepared local attachments awaiting upload — shared by the single-task
@@ -1320,8 +1343,7 @@ class _BaseClient:
             data["title"] = title
         if content is not None:
             data["content"] = content
-        if critical:
-            data["critical"] = critical
+        data.update(_priority_wire(priority, critical, critical_volume))
         if reply is not None:
             data["reply"] = reply.value if isinstance(reply, ReplyMode) else reply
         if content_format is not None:
@@ -1332,14 +1354,14 @@ class _BaseClient:
 
     def _append_subtask(self, task, *, title=None, content=None, inputs=None,
                         links=None, files=None,
-                        auto_commit=False, critical=False,
+                        auto_commit=False, critical=False, priority=None, critical_volume=None,
                         reply=None, content_format=None) -> Subtask:
         if not task.append_token:
             raise RuntimeError("this task has no append token; cannot append a subtask")
         # Inherit the parent's key (subtask encryption must match the chain's).
         data, prepared = self._build_subtask_data(
             task._send_key, title=title, content=content, inputs=inputs,
-            links=links, files=files, auto_commit=auto_commit, critical=critical,
+            links=links, files=files, auto_commit=auto_commit, critical=critical, priority=priority, critical_volume=critical_volume,
             reply=reply, content_format=content_format,
         )
 
@@ -1369,7 +1391,7 @@ class _BaseClient:
 
     def _append_subtasks_to_group(self, group, *, instances=None, title=None,
                                   content=None, inputs=None, links=None, files=None,
-                                  auto_commit=False, critical=False,
+                                  auto_commit=False, critical=False, priority=None, critical_volume=None,
                                   reply=None, content_format=None) -> "list[Subtask]":
         """Append one subtask per member instance to a task group's chains,
         atomically, via the group append token. `instances` (task ids) restricts
@@ -1381,7 +1403,7 @@ class _BaseClient:
             raise RuntimeError("this task group has no append token; cannot append a subtask")
         data, prepared = self._build_subtask_data(
             group._send_key, title=title, content=content, inputs=inputs,
-            links=links, files=files, auto_commit=auto_commit, critical=critical,
+            links=links, files=files, auto_commit=auto_commit, critical=critical, priority=priority, critical_volume=critical_volume,
             reply=reply, content_format=content_format,
         )
 
@@ -1502,7 +1524,7 @@ class _BaseClient:
             attempt += 1
             req = urllib.request.Request(url, data=data, headers=req_headers, method="POST")
             try:
-                with urllib.request.urlopen(req) as resp:
+                with urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT) as resp:
                     resp_body = resp.read().decode("utf-8")
                     if resp_body:
                         return json.loads(resp_body)
@@ -1513,8 +1535,9 @@ class _BaseClient:
                 if not (retry and retryable) or attempt >= self._RETRY_MAX_ATTEMPTS:
                     raise ApiError(e.code, payload) from e
                 time.sleep(self._retry_delay(attempt, e.headers.get("Retry-After")))
-            except urllib.error.URLError as e:
-                # Network-level failure (connection refused/reset, DNS).
+            except (urllib.error.URLError, TimeoutError) as e:
+                # Network-level failure (connection refused/reset, DNS, or no
+                # response within the timeout).
                 if not retry or attempt >= self._RETRY_MAX_ATTEMPTS:
                     raise
                 time.sleep(self._retry_delay(attempt, None))
@@ -1526,7 +1549,7 @@ class _BaseClient:
         url = f"{self._base}{path}"
         req = urllib.request.Request(url, data=b"", headers=dict(headers or {}), method="POST")
         try:
-            with urllib.request.urlopen(req) as resp:
+            with urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT) as resp:
                 resp_body = resp.read().decode("utf-8")
                 return json.loads(resp_body) if resp_body else None
         except urllib.error.HTTPError as e:
@@ -1539,7 +1562,7 @@ class _BaseClient:
         req = urllib.request.Request(url, data=data, method="PUT")
         req.add_header("Content-Type", "application/octet-stream")
         try:
-            with urllib.request.urlopen(req) as resp:
+            with urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT) as resp:
                 resp.read()
         except urllib.error.HTTPError as e:
             raise ApiError(e.code, e.read().decode("utf-8")) from e

{simplepush-3.6.1 → simplepush-3.7.1}/src/simplepush/client.py

@@ -49,6 +49,10 @@ from urllib.parse import quote
 import websockets
 import websockets.exceptions
 
+# Seconds an HTTP request waits for the connection or the next data before it
+# fails. It bounds each wait, not a whole upload or download.
+_HTTP_TIMEOUT = 30
+
 if TYPE_CHECKING:
     # Type-only: api.py imports from this module at runtime, so a real import
     # here would be circular. The enum-or-Literal unions below give static
@@ -276,7 +280,7 @@ class _DownloadTransport:
         url = f"{self._base}/{scope}/{quote(str(scope_id))}/{kind}/{quote(str(file_id))}/download-url"
         req = urllib.request.Request(url, data=b"", headers=self._headers, method="POST")
         try:
-            with urllib.request.urlopen(req) as resp:
+            with urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT) as resp:
                 body = resp.read().decode("utf-8")
         except urllib.error.HTTPError as e:
             detail = e.read().decode("utf-8", "replace")
@@ -286,7 +290,7 @@ class _DownloadTransport:
 
     def get(self, url: str) -> bytes:
         try:
-            with urllib.request.urlopen(url) as resp:
+            with urllib.request.urlopen(url, timeout=_HTTP_TIMEOUT) as resp:
                 return resp.read()
         except urllib.error.HTTPError as e:
             raise DownloadError(f"file fetch failed: HTTP {e.code}", status_code=e.code) from e
@@ -1472,6 +1476,7 @@ class Task:
                inputs=None, links: list[str] | None = None,
                files: "list[str | os.PathLike] | None" = None,
                auto_commit: bool = False, critical: bool = False,
+               priority: int | None = None, critical_volume: float | None = None,
                reply: "ReplyMode | Literal['one-shot', 'sticky', 'one-time-per-user'] | None" = None,
                content_format: "ContentFormat | Literal['plain', 'markdown'] | None" = None) -> "Subtask":
         """Append a subtask to this task's chain and return a `Subtask` handle.
@@ -1486,7 +1491,7 @@ class Task:
         return self._client._append_subtask(
             self, title=title, content=content, inputs=inputs,
             links=links, files=files,
-            auto_commit=auto_commit, critical=critical, reply=reply,
+            auto_commit=auto_commit, critical=critical, priority=priority, critical_volume=critical_volume, reply=reply,
             content_format=content_format,
         )
 
@@ -1644,6 +1649,7 @@ class TaskGroup:
                files: "list[str | os.PathLike] | None" = None,
                instances: "list[str | Task] | None" = None,
                auto_commit: bool = False, critical: bool = False,
+               priority: int | None = None, critical_volume: float | None = None,
                reply: "ReplyMode | Literal['one-shot', 'sticky', 'one-time-per-user'] | None" = None,
                content_format: "ContentFormat | Literal['plain', 'markdown'] | None" = None) -> "list[Subtask]":
         """Append a subtask to every member instance's chain atomically — or
@@ -1661,7 +1667,7 @@ class TaskGroup:
             ids = [t.task_id if isinstance(t, Task) else t for t in instances]
         return self._client._append_subtasks_to_group(
             self, instances=ids, title=title, content=content, inputs=inputs,
-            links=links, files=files, auto_commit=auto_commit, critical=critical,
+            links=links, files=files, auto_commit=auto_commit, critical=critical, priority=priority, critical_volume=critical_volume,
             reply=reply, content_format=content_format,
         )