pernox 0.1.0__py3-none-any.whl

pernox/__init__.py

@@ -0,0 +1,96 @@
+"""Send yourself a notification from a script running in nox.
+
+    from pernox import notify
+
+    notify("3 new flats under £1,500", title="Flat search")
+
+Inside nox, each run is given a token (NOX_TOKEN) and nox's address (NOX_API_URL), so
+there's nothing to set up. Anywhere else, notify prints the message instead of sending it,
+so the same script runs on your own machine unchanged.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from importlib.metadata import PackageNotFoundError, version
+from typing import Optional
+
+__all__ = ["notify", "NotifyError"]
+try:
+    __version__ = version("pernox")
+except PackageNotFoundError:  # run from the source tree without installing
+    __version__ = "0.0.0"
+
+_DEFAULT_API_URL = "https://pernox.dev"
+
+
+class NotifyError(Exception):
+    """nox couldn't send the notification. status is the HTTP status, if nox answered."""
+
+    def __init__(self, message: str, status: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.status = status
+
+
+def notify(
+    message: str,
+    title: Optional[str] = None,
+    *,
+    url: Optional[str] = None,
+    timeout: float = 60,
+) -> bool:
+    """Email the script's owner, at their nox account's address.
+
+    message: the text, up to 1,024 characters.
+    title: the subject line, up to 250 characters. Without one, it's the script's name.
+    url: a link to include.
+
+    Returns True once sent, or False if it was printed instead because the script isn't
+    running in nox. Raises NotifyError if nox couldn't send it.
+    """
+    token = os.environ.get("NOX_TOKEN")
+    if not token:
+        heading = f"{title}: " if title else ""
+        print(f"[pernox] {heading}{message} (not sent: runs outside nox)", file=sys.stderr)
+        return False
+
+    body = {"channel": "email", "message": message}
+    if title is not None:
+        body["title"] = title
+    if url is not None:
+        body["url"] = url
+    api = os.environ.get("NOX_API_URL", _DEFAULT_API_URL).rstrip("/")
+    request = urllib.request.Request(
+        api + "/api/v1/notify",
+        data=json.dumps(body).encode(),
+        method="POST",
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+            "User-Agent": f"pernox/{__version__}",
+        },
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            response.read()
+    except urllib.error.HTTPError as e:
+        raise NotifyError(_error_message(e), e.code) from None
+    except (urllib.error.URLError, TimeoutError) as e:
+        reason = getattr(e, "reason", e)
+        raise NotifyError(f"Couldn't reach nox at {api}: {reason}") from None
+    return True
+
+
+def _error_message(e: urllib.error.HTTPError) -> str:
+    """nox explains what went wrong in the body's "error"; fall back to the status."""
+    try:
+        message = json.loads(e.read())["error"]
+        if isinstance(message, str) and message:
+            return message
+    except (ValueError, KeyError, TypeError, OSError):
+        pass
+    return f"nox answered {e.code} {e.reason}"

pernox-0.1.0.dist-info/METADATA

@@ -0,0 +1,53 @@
+Metadata-Version: 2.5
+Name: pernox
+Version: 0.1.0
+Summary: Email yourself from a script running in nox.
+Project-URL: Homepage, https://pernox.dev
+Project-URL: Documentation, https://pernox.dev/docs#notify
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cron,email,notifications,nox,scheduler
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# pernox
+
+Email yourself from a script running in [nox](https://pernox.dev).
+
+```
+pip install pernox
+```
+
+```python
+from pernox import notify
+
+notify("3 new flats under £1,500", title="Flat search")
+```
+
+In nox, add `pernox` to the script's requirements. There's nothing else to set up: each run
+is given its own token, which stops working when the run ends, and the email goes to your
+nox account's address.
+
+Notifications come with nox Pro, and go only to a verified address: verify yours in
+[Settings](https://pernox.dev/settings#profile).
+
+Run the script anywhere else and `notify` prints the message instead of sending it, so the
+same script works on your own machine.
+
+`notify` returns `True` once the email is sent, and `False` when it was only printed. If nox
+can't send it, it raises `pernox.NotifyError`, which fails the run like any other exception.
+Catch it if a notification failing shouldn't.
+
+## Arguments
+
+| | |
+|---|---|
+| `message` | The text, up to 1,024 characters. |
+| `title` | The subject line, up to 250 characters. Without one, it's the script's name. |
+| `url` | A link to include. |
+
+No dependencies beyond the standard library. Python 3.10 or later. MIT licensed.

pernox-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+pernox/__init__.py,sha256=ab6XSWPpbZ_LniPcgH4gdYggTe3KbvvkfpFEXTbeyDg,3164
+pernox/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pernox-0.1.0.dist-info/METADATA,sha256=KZhlouRLi6CeN4B_M7Mt1cZKBEKqC6OAtXYBGRlZo5w,1717
+pernox-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+pernox-0.1.0.dist-info/licenses/LICENSE,sha256=eCpx3f9Nysno3SsZ6BrvWggy72c7hDCfuIDLOtBdwu8,1080
+pernox-0.1.0.dist-info/RECORD,,

pernox-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pernox-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastien Williams-Wynn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.