pernox 0.1.0__tar.gz

pernox-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,93 @@
+# Releases pernox on every merge to main that changes the package: works out the next
+# version from the latest v* tag, builds it, publishes it to PyPI, and then tags the commit.
+#
+# The bump is a patch (0.1.3 -> 0.1.4) unless the merge's commit message says otherwise:
+# put #minor or #major in the pull request's title or description. The first release is
+# 0.1.0.
+#
+# Nothing is committed back to main: the version lives only in the tag, which hatch-vcs
+# reads when building. The tag is pushed after PyPI accepts the release, so a failed
+# publish leaves no tag behind and the next merge tries the same version again.
+#
+# Publishing uses PyPI's trusted publishing, so no PyPI token is stored here: PyPI trusts
+# this workflow, in the "pypi" environment, to upload pernox.
+name: release
+
+on:
+  push:
+    branches: [main]
+    paths: [src/**, pyproject.toml, README.md, LICENSE]
+
+# One release at a time, in order, so two quick merges don't claim the same version.
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  test:
+    uses: ./.github/workflows/test.yml
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.next.outputs.version }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # every tag, to find the latest version
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+      - name: Work out the next version
+        id: next
+        env:
+          MESSAGE: ${{ github.event.head_commit.message }}
+        run: |
+          latest=$(git tag --list 'v[0-9]*.[0-9]*.[0-9]*' --sort=-version:refname | head -n 1)
+          if [ -z "$latest" ]; then
+            next=0.1.0
+          else
+            IFS=. read -r major minor patch <<< "${latest#v}"
+            case "$MESSAGE" in
+              *"#major"*) next="$((major + 1)).0.0" ;;
+              *"#minor"*) next="$major.$((minor + 1)).0" ;;
+              *)          next="$major.$minor.$((patch + 1))" ;;
+            esac
+          fi
+          echo "Releasing $next (latest was ${latest:-none})"
+          echo "version=$next" >> "$GITHUB_OUTPUT"
+      # Tagged here only so hatch-vcs builds this version; it's pushed once PyPI has it.
+      - run: git tag "v${{ steps.next.outputs.version }}"
+      - run: python -m pip install build
+      - run: python -m build
+      - name: Check the build has the right version
+        run: ls dist/ | grep -q "pernox-${{ steps.next.outputs.version }}-py3-none-any.whl"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  tag:
+    needs: [build, publish]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+      - run: |
+          git tag "v${{ needs.build.outputs.version }}" "$GITHUB_SHA"
+          git push origin "v${{ needs.build.outputs.version }}"

pernox-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,21 @@
+# Tests every pull request and push. The release workflow runs it too, before publishing.
+name: test
+
+on:
+  push:
+  pull_request:
+  workflow_call:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # The oldest Python pernox supports, and the newest.
+        python: ["3.10", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+      - run: PYTHONPATH=src python -m unittest discover -s tests -v

pernox-0.1.0/.gitignore

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

pernox-0.1.0/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.

pernox-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,37 @@
+# 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/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling>=1.25", "hatch-vcs>=0.4"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pernox"
+# The version is the latest v* git tag, which the release workflow creates on each merge.
+dynamic = ["version"]
+description = "Email yourself from a script running in nox."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+# No dependencies: it only needs the standard library, so it installs instantly in a run.
+dependencies = []
+keywords = ["nox", "notifications", "email", "scheduler", "cron"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Communications",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://pernox.dev"
+Documentation = "https://pernox.dev/docs#notify"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+# Outside a git checkout with tags, as in a bare copy of the source.
+fallback_version = "0.0.0"

pernox-0.1.0/src/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/tests/test_notify.py

@@ -0,0 +1,86 @@
+import io
+import json
+import os
+import threading
+import unittest
+from contextlib import redirect_stderr
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from unittest import mock
+
+import pernox
+
+
+class FakeNox(BaseHTTPRequestHandler):
+    """Answers /api/v1/notify like nox: the token "good" works, anything else doesn't."""
+
+    received = []
+
+    def do_POST(self):
+        body = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
+        FakeNox.received.append((self.path, self.headers["Authorization"], body))
+        if self.headers["Authorization"] != "Bearer good":
+            self.reply(401, {"error": "This token isn't valid."})
+        else:
+            self.reply(200, {"sent": True, "channel": body["channel"]})
+
+    def reply(self, status, body):
+        data = json.dumps(body).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+    def log_message(self, *args):
+        pass
+
+
+class NotifyTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.server = HTTPServer(("127.0.0.1", 0), FakeNox)
+        threading.Thread(target=cls.server.serve_forever, daemon=True).start()
+        cls.url = f"http://127.0.0.1:{cls.server.server_port}"
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+
+    def setUp(self):
+        FakeNox.received.clear()
+
+    def env(self, token):
+        return mock.patch.dict(os.environ, {"NOX_TOKEN": token, "NOX_API_URL": self.url + "/"})
+
+    def test_sends_inside_nox(self):
+        with self.env("good"):
+            sent = pernox.notify("All done", title="Backup", url="https://example.com")
+        self.assertTrue(sent)
+        path, auth, body = FakeNox.received[0]
+        self.assertEqual(path, "/api/v1/notify")
+        self.assertEqual(auth, "Bearer good")
+        self.assertEqual(body, {"channel": "email", "message": "All done", "title": "Backup", "url": "https://example.com"})
+
+    def test_raises_nox_error_message(self):
+        with self.env("bad"), self.assertRaises(pernox.NotifyError) as caught:
+            pernox.notify("All done")
+        self.assertEqual(str(caught.exception), "This token isn't valid.")
+        self.assertEqual(caught.exception.status, 401)
+
+    def test_raises_when_nox_is_unreachable(self):
+        with mock.patch.dict(os.environ, {"NOX_TOKEN": "good", "NOX_API_URL": "http://127.0.0.1:9"}):
+            with self.assertRaises(pernox.NotifyError) as caught:
+                pernox.notify("All done")
+        self.assertIn("Couldn't reach nox", str(caught.exception))
+
+    def test_prints_outside_nox(self):
+        env = {k: v for k, v in os.environ.items() if k != "NOX_TOKEN"}
+        with mock.patch.dict(os.environ, env, clear=True), redirect_stderr(io.StringIO()) as err:
+            sent = pernox.notify("All done", title="Backup")
+        self.assertFalse(sent)
+        self.assertEqual(FakeNox.received, [])
+        self.assertIn("[pernox] Backup: All done (not sent: runs outside nox)", err.getvalue())
+
+
+if __name__ == "__main__":
+    unittest.main()