youlmk 0.1.0__tar.gz

youlmk-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+dist/
+build/
+__pycache__/
+*.egg-info/

youlmk-0.1.0/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.5
+Name: youlmk
+Version: 0.1.0
+Summary: Send a notification to your YouLMK inbox from Python. One call, no dependencies.
+Project-URL: Homepage, https://youlmk.com
+Project-URL: Documentation, https://youlmk.com/docs/sdks
+Project-URL: Source, https://github.com/bylivebetter/youlmk
+Author: Live Better Platforms, Inc.
+License-Expression: MIT
+Keywords: alerts,notifications,push,webhook,youlmk
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# youlmk
+
+Send a notification to your [YouLMK](https://youlmk.com) inbox with one call. Python 3.9+, the standard library only.
+
+```bash
+pip install youlmk
+```
+
+```python
+from youlmk import notify
+
+notify(os.environ["YOULMK_TOKEN"], "backup finished", body="4.2 GB in 3 min 10 s", priority="low")
+```
+
+The token is your source's bearer token (`ylk_…`), from the source's page. Every option is in the [payload reference](https://youlmk.com/docs/payload); the answer is a `Result(id, receipt, grouped, held)`; an error is a `YouLMKError` with the door's `code`, the `field` for a 422, and `retry_after` for a 429.
+
+Docs: https://youlmk.com/docs/sdks

youlmk-0.1.0/README.md

@@ -0,0 +1,17 @@
+# youlmk
+
+Send a notification to your [YouLMK](https://youlmk.com) inbox with one call. Python 3.9+, the standard library only.
+
+```bash
+pip install youlmk
+```
+
+```python
+from youlmk import notify
+
+notify(os.environ["YOULMK_TOKEN"], "backup finished", body="4.2 GB in 3 min 10 s", priority="low")
+```
+
+The token is your source's bearer token (`ylk_…`), from the source's page. Every option is in the [payload reference](https://youlmk.com/docs/payload); the answer is a `Result(id, receipt, grouped, held)`; an error is a `YouLMKError` with the door's `code`, the `field` for a 422, and `retry_after` for a 429.
+
+Docs: https://youlmk.com/docs/sdks

youlmk-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "youlmk"
+version = "0.1.0"
+description = "Send a notification to your YouLMK inbox from Python. One call, no dependencies."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Live Better Platforms, Inc." }]
+keywords = ["notifications", "push", "youlmk", "alerts", "webhook"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Topic :: Communications",
+]
+
+[project.urls]
+Homepage = "https://youlmk.com"
+Documentation = "https://youlmk.com/docs/sdks"
+Source = "https://github.com/bylivebetter/youlmk"
+
+[tool.hatch.build.targets.wheel]
+packages = ["youlmk"]
+
+[tool.hatch.build.targets.sdist]
+include = ["youlmk", "tests", "README.md", "pyproject.toml"]

youlmk-0.1.0/tests/test_notify.py

@@ -0,0 +1,82 @@
+import io
+import json
+import os
+import unittest
+import urllib.error
+from email.message import Message
+
+from youlmk import Result, YouLMK, YouLMKError, notify, to_payload
+
+
+class Answer(io.BytesIO):
+    """What urllib hands back: a body with a status and headers."""
+
+    def __init__(self, status, body, headers=None):
+        super().__init__(json.dumps(body).encode())
+        self.status = status
+        self.headers = Message()
+        for k, v in (headers or {}).items():
+            self.headers[k] = v
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.close()
+
+
+class Opener:
+    def __init__(self, status, body, headers=None):
+        self.status, self.body, self.headers = status, body, headers
+        self.requests = []
+
+    def open(self, request, timeout=None):
+        self.requests.append(request)
+        if self.status >= 400:
+            msg = Message()
+            for k, v in (self.headers or {}).items():
+                msg[k] = v
+            raise urllib.error.HTTPError(request.full_url, self.status, "error", msg, io.BytesIO(json.dumps(self.body).encode()))
+        return Answer(self.status, self.body, self.headers)
+
+
+class NotifyTests(unittest.TestCase):
+    def test_posts_the_token_and_the_snake_case_payload(self):
+        door = Opener(200, {"ok": True, "id": "ntf_1", "receipt": "rcpt_1", "grouped": False, "held": True})
+        result = YouLMK("ylk_test", base_url="https://door.test/", opener=door).notify("deploy finished", body="4 min", priority="high", url="https://x.test/1", url_label="Logs", fields={"Env": "prod"}, idempotency_key="run-9")
+        self.assertEqual(result, Result(id="ntf_1", receipt="rcpt_1", grouped=False, held=True))
+        request = door.requests[0]
+        self.assertEqual(request.full_url, "https://door.test/v1/notify")
+        self.assertEqual(request.get_header("Authorization"), "Bearer ylk_test")
+        self.assertEqual(request.get_header("Idempotency-key"), "run-9")
+        self.assertEqual(json.loads(request.data), {"title": "deploy finished", "body": "4 min", "priority": "high", "url": "https://x.test/1", "url_label": "Logs", "fields": {"Env": "prod"}})
+
+    def test_leaves_out_what_was_not_given(self):
+        self.assertEqual(to_payload("hi"), {"title": "hi"})
+
+    def test_errors_carry_the_code_the_field_and_retry_after(self):
+        with self.assertRaises(YouLMKError) as limited:
+            YouLMK("ylk_test", opener=Opener(429, {"error": "rate_limited"}, {"Retry-After": "7"})).notify("x")
+        self.assertEqual((limited.exception.status, limited.exception.code, limited.exception.retry_after), (429, "rate_limited", 7))
+        with self.assertRaises(YouLMKError) as invalid:
+            YouLMK("ylk_test", opener=Opener(422, {"error": "invalid_field", "field": "priority"})).notify("x")
+        self.assertEqual(invalid.exception.field, "priority")
+        self.assertIn("priority", str(invalid.exception))
+
+    def test_refuses_an_empty_token(self):
+        with self.assertRaises(YouLMKError):
+            YouLMK("")
+
+
+@unittest.skipUnless(os.environ.get("YOULMK_TOKEN"), "no token in the environment")
+class LiveTests(unittest.TestCase):
+    """One notification into the dev inbox, from this package, when a token is in the environment."""
+
+    def test_sends_one(self):
+        result = notify(os.environ["YOULMK_TOKEN"], "youlmk-python sent this", body="from the package's own test", priority="low", base_url=os.environ.get("YOULMK_BASE", "https://youlmk.com"))
+        self.assertTrue(result.id.startswith("ntf_"))
+        self.assertTrue(result.receipt.startswith("rcpt_"))
+
+
+if __name__ == "__main__":
+    unittest.main()

youlmk-0.1.0/youlmk/__init__.py

@@ -0,0 +1,178 @@
+"""youlmk: send a notification to your inbox with one call.
+
+    from youlmk import notify
+    notify(os.environ["YOULMK_TOKEN"], "backup finished", body="4.2 GB in 3 min 10 s")
+
+Wraps POST youlmk.com/v1/notify with the source's bearer token
+(https://youlmk.com/docs/http). The standard library only.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Mapping, Optional, Sequence
+
+__all__ = ["YouLMK", "YouLMKError", "Result", "notify", "to_payload", "__version__"]
+__version__ = "0.1.0"
+
+DEFAULT_BASE = "https://youlmk.com"
+
+_MESSAGES = {
+    "unknown_key": "No source has this token",
+    "key_rotated": "This token was rotated or its source deleted",
+    "trial_used": "The free notifications are used; subscribe to keep sending",
+    "too_large": "The payload is over 8 KB",
+    "rate_limited": "Too many sends; wait retry_after seconds",
+    "daily_cap": "The account's daily cap is reached",
+    "sending_paused": "Sending is paused; try again shortly",
+    "bad_json": "The body was not JSON",
+    "network": "YouLMK could not be reached",
+}
+
+
+class YouLMKError(Exception):
+    """The door answered with an error, or could not be reached.
+
+    status: the HTTP status, or 0 when nothing came back.
+    code: the door's own word (unknown_key, trial_used, invalid_field, rate_limited, ...).
+    field: for invalid_field, which one.
+    retry_after: for rate_limited, daily_cap and sending_paused, seconds to wait.
+    """
+
+    def __init__(self, status: int, code: str, field: Optional[str] = None, retry_after: Optional[int] = None):
+        self.status = status
+        self.code = code
+        self.field = field
+        self.retry_after = retry_after
+        if code == "invalid_field":
+            message = f"The {field or 'payload'} is over its limit or the wrong shape"
+        else:
+            message = _MESSAGES.get(code) or f"YouLMK answered {status}" + (f" ({code})" if code else "")
+        super().__init__(message)
+
+
+@dataclass(frozen=True)
+class Result:
+    """What the door answers: the notification's id, its receipt, and two facts about where it went."""
+
+    id: str
+    receipt: str
+    grouped: bool
+    held: bool
+
+
+def to_payload(
+    title: str,
+    *,
+    body: Optional[str] = None,
+    priority: Optional[str] = None,
+    url: Optional[str] = None,
+    url_label: Optional[str] = None,
+    actions: Optional[Sequence[Mapping[str, str]]] = None,
+    group: Optional[str] = None,
+    image: Optional[str] = None,
+    fields: Optional[Mapping[str, str]] = None,
+) -> dict[str, Any]:
+    """The JSON the door reads: snake_case, with nothing None in it."""
+    payload: dict[str, Any] = {"title": title}
+    if body is not None:
+        payload["body"] = body
+    if priority is not None:
+        payload["priority"] = priority
+    if url is not None:
+        payload["url"] = url
+    if url_label is not None:
+        payload["url_label"] = url_label
+    if actions is not None:
+        payload["actions"] = [dict(a) for a in actions]
+    if group is not None:
+        payload["group"] = group
+    if image is not None:
+        payload["image"] = image
+    if fields is not None:
+        payload["fields"] = dict(fields)
+    return payload
+
+
+class YouLMK:
+    """A client bound to one source's token, for code that sends more than once."""
+
+    def __init__(self, token: str, *, base_url: str = DEFAULT_BASE, timeout: float = 10.0, opener: Any = None):
+        if not token or not isinstance(token, str):
+            raise YouLMKError(0, "unknown_key")
+        self._token = token
+        self._base = base_url.rstrip("/")
+        self._timeout = timeout
+        # A urllib opener to use instead of the default; the tests hand in one that answers without a network.
+        self._opener = opener or urllib.request.build_opener()
+
+    def notify(
+        self,
+        title: str,
+        *,
+        body: Optional[str] = None,
+        priority: Optional[str] = None,
+        url: Optional[str] = None,
+        url_label: Optional[str] = None,
+        actions: Optional[Sequence[Mapping[str, str]]] = None,
+        group: Optional[str] = None,
+        image: Optional[str] = None,
+        fields: Optional[Mapping[str, str]] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Result:
+        """Send one notification. Returns its id and receipt; raises YouLMKError."""
+        payload = to_payload(title, body=body, priority=priority, url=url, url_label=url_label, actions=actions, group=group, image=image, fields=fields)
+        data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        request = urllib.request.Request(
+            f"{self._base}/v1/notify",
+            data=data,
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {self._token}",
+                "Content-Type": "application/json",
+                "User-Agent": f"youlmk-python/{__version__}",
+            },
+        )
+        if idempotency_key:
+            request.add_header("Idempotency-Key", idempotency_key)
+        try:
+            with self._opener.open(request, timeout=self._timeout) as response:
+                status = response.status
+                text = response.read().decode("utf-8")
+                retry_header = response.headers.get("Retry-After")
+        except urllib.error.HTTPError as error:
+            status = error.code
+            text = error.read().decode("utf-8", errors="replace")
+            retry_header = error.headers.get("Retry-After") if error.headers else None
+        except (urllib.error.URLError, OSError) as error:
+            raise YouLMKError(0, "network") from error
+        try:
+            answer = json.loads(text) if text else {}
+        except ValueError:
+            answer = {}
+        if not isinstance(answer, dict):
+            answer = {}
+        if status < 200 or status >= 300:
+            retry_after = None
+            if retry_header:
+                try:
+                    retry_after = int(retry_header)
+                except ValueError:
+                    retry_after = None
+            code = answer.get("error") if isinstance(answer.get("error"), str) else ""
+            field = answer.get("field") if isinstance(answer.get("field"), str) else None
+            raise YouLMKError(status, code, field=field, retry_after=retry_after)
+        return Result(
+            id=str(answer.get("id", "")),
+            receipt=str(answer.get("receipt", "")),
+            grouped=answer.get("grouped") is True,
+            held=answer.get("held") is True,
+        )
+
+
+def notify(token: str, title: str, *, base_url: str = DEFAULT_BASE, timeout: float = 10.0, **options: Any) -> Result:
+    """Send one notification with a source's token. The same as YouLMK(token).notify(title, ...)."""
+    return YouLMK(token, base_url=base_url, timeout=timeout).notify(title, **options)