aailab-tools 0.1.0__tar.gz

aailab_tools-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: aailab-tools
+Version: 0.1.0
+Summary: Utilities for interacting with the AAILab blade dashboard.
+Author: AAILab
+License: MIT
+Project-URL: Homepage, https://github.com/vrbaj/aailab-tools
+Keywords: decorator,notification,email,blade-dashboard
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+
+# aailab-tools
+
+`aailab-tools` provides a `notify()` decorator that reports the completion status
+of a function to the `blade_dashboard` notification API.
+
+## Installation
+
+```bash
+pip install aailab-tools
+```
+
+## Configuration
+
+The decorator reads its configuration from environment variables:
+
+- `SERVER_NOTIFY`: full notification endpoint URL, for example
+  `http://127.0.0.1:8000/api/notify`
+- `API_TOKEN`: API token expected by `blade_dashboard server`
+- `AAILAB_MACHINE_ID`: optional machine identifier; if omitted, hostname is used
+
+## Usage
+
+```python
+from aailab_tools import notify
+
+
+@notify("user@example.com", "admin@example.com")
+def run_job():
+    return 42
+```
+
+On success, the server receives status `0`. If the function raises an exception,
+the exception text is sent as the status and the exception is re-raised.

aailab_tools-0.1.0/README.md

@@ -0,0 +1,33 @@
+# aailab-tools
+
+`aailab-tools` provides a `notify()` decorator that reports the completion status
+of a function to the `blade_dashboard` notification API.
+
+## Installation
+
+```bash
+pip install aailab-tools
+```
+
+## Configuration
+
+The decorator reads its configuration from environment variables:
+
+- `SERVER_NOTIFY`: full notification endpoint URL, for example
+  `http://127.0.0.1:8000/api/notify`
+- `API_TOKEN`: API token expected by `blade_dashboard server`
+- `AAILAB_MACHINE_ID`: optional machine identifier; if omitted, hostname is used
+
+## Usage
+
+```python
+from aailab_tools import notify
+
+
+@notify("user@example.com", "admin@example.com")
+def run_job():
+    return 42
+```
+
+On success, the server receives status `0`. If the function raises an exception,
+the exception text is sent as the status and the exception is re-raised.

aailab_tools-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aailab-tools"
+version = "0.1.0"
+description = "Utilities for interacting with the AAILab blade dashboard."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "requests>=2.31.0",
+]
+authors = [
+    { name = "AAILab" },
+]
+license = { text = "MIT" }
+keywords = ["decorator", "notification", "email", "blade-dashboard"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+[project.urls]
+Homepage = "https://github.com/vrbaj/aailab-tools"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

aailab_tools-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aailab_tools-0.1.0/src/aailab_tools/__init__.py

@@ -0,0 +1,3 @@
+from .notify import notify
+
+__all__ = ["notify"]

aailab_tools-0.1.0/src/aailab_tools/notify.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import functools
+import inspect
+import os
+import socket
+from typing import Any, Callable, TypeVar, cast
+
+import requests
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class NotificationConfigurationError(RuntimeError):
+    """Raised when required notification configuration is missing."""
+
+
+def _machine_id() -> str:
+    return os.environ.get("AAILAB_MACHINE_ID") or socket.gethostname()
+
+
+def _validate_emails(emails: tuple[str, ...]) -> list[str]:
+    cleaned = [email.strip() for email in emails if email.strip()]
+    if not cleaned:
+        raise ValueError("notify() requires at least one email address")
+
+    invalid = [email for email in cleaned if "@" not in email]
+    if invalid:
+        raise ValueError(f"invalid email address(es): {', '.join(invalid)}")
+
+    return cleaned
+
+
+def _notify_server(task_name: str, status: int | str, emails: list[str]) -> None:
+    endpoint = os.environ.get("SERVER_NOTIFY", "").strip()
+    api_token = os.environ.get("API_TOKEN", "").strip()
+
+    if not endpoint:
+        raise NotificationConfigurationError("SERVER_NOTIFY is not configured")
+    if not api_token:
+        raise NotificationConfigurationError("API_TOKEN is not configured")
+
+    response = requests.post(
+        endpoint,
+        headers={
+            "Content-Type": "application/json",
+            "X-API-TOKEN": api_token,
+        },
+        json={
+            "machine_id": _machine_id(),
+            "task_name": task_name,
+            "status": status,
+            "emails": emails,
+        },
+        timeout=15,
+    )
+    response.raise_for_status()
+
+
+def notify(*emails: str) -> Callable[[F], F]:
+    """Notify the blade_dashboard server when the decorated function finishes."""
+
+    recipients = _validate_emails(emails)
+
+    def decorator(func: F) -> F:
+        task_name = func.__qualname__
+
+        @functools.wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            try:
+                result = func(*args, **kwargs)
+            except Exception as exc:
+                _notify_server(task_name=task_name, status=str(exc), emails=recipients)
+                raise
+
+            _notify_server(task_name=task_name, status=0, emails=recipients)
+            return result
+
+        @functools.wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            try:
+                result = await cast(Any, func)(*args, **kwargs)
+            except Exception as exc:
+                _notify_server(task_name=task_name, status=str(exc), emails=recipients)
+                raise
+
+            _notify_server(task_name=task_name, status=0, emails=recipients)
+            return result
+
+        if inspect.iscoroutinefunction(func):
+            return cast(F, async_wrapper)
+        return cast(F, sync_wrapper)
+
+    return decorator

aailab_tools-0.1.0/src/aailab_tools.egg-info/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: aailab-tools
+Version: 0.1.0
+Summary: Utilities for interacting with the AAILab blade dashboard.
+Author: AAILab
+License: MIT
+Project-URL: Homepage, https://github.com/vrbaj/aailab-tools
+Keywords: decorator,notification,email,blade-dashboard
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+
+# aailab-tools
+
+`aailab-tools` provides a `notify()` decorator that reports the completion status
+of a function to the `blade_dashboard` notification API.
+
+## Installation
+
+```bash
+pip install aailab-tools
+```
+
+## Configuration
+
+The decorator reads its configuration from environment variables:
+
+- `SERVER_NOTIFY`: full notification endpoint URL, for example
+  `http://127.0.0.1:8000/api/notify`
+- `API_TOKEN`: API token expected by `blade_dashboard server`
+- `AAILAB_MACHINE_ID`: optional machine identifier; if omitted, hostname is used
+
+## Usage
+
+```python
+from aailab_tools import notify
+
+
+@notify("user@example.com", "admin@example.com")
+def run_job():
+    return 42
+```
+
+On success, the server receives status `0`. If the function raises an exception,
+the exception text is sent as the status and the exception is re-raised.

aailab_tools-0.1.0/src/aailab_tools.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+src/aailab_tools/__init__.py
+src/aailab_tools/notify.py
+src/aailab_tools.egg-info/PKG-INFO
+src/aailab_tools.egg-info/SOURCES.txt
+src/aailab_tools.egg-info/dependency_links.txt
+src/aailab_tools.egg-info/requires.txt
+src/aailab_tools.egg-info/top_level.txt
+tests/test_notify.py

aailab_tools-0.1.0/src/aailab_tools.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

aailab_tools-0.1.0/src/aailab_tools.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.31.0

aailab_tools-0.1.0/src/aailab_tools.egg-info/top_level.txt

@@ -0,0 +1 @@
+aailab_tools

aailab_tools-0.1.0/tests/test_notify.py

@@ -0,0 +1,122 @@
+import asyncio
+import unittest
+
+from aailab_tools import notify
+
+
+class NotifyTests(unittest.TestCase):
+    def setUp(self):
+        self._env = {}
+
+    def tearDown(self):
+        import os
+
+        for key, previous in self._env.items():
+            if previous is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = previous
+
+    def set_env(self, key, value):
+        import os
+
+        if key not in self._env:
+            self._env[key] = os.environ.get(key)
+        os.environ[key] = value
+
+    def patch_post(self, fake_post):
+        from unittest.mock import patch
+
+        return patch("aailab_tools.notify.requests.post", fake_post)
+
+    def test_notify_sends_success_payload(self):
+        captured = {}
+
+        class FakeResponse:
+            def raise_for_status(self):
+                return None
+
+        def fake_post(url, headers, json, timeout):
+            captured["url"] = url
+            captured["headers"] = headers
+            captured["json"] = json
+            captured["timeout"] = timeout
+            return FakeResponse()
+
+        self.set_env("SERVER_NOTIFY", "http://example.test/api/notify")
+        self.set_env("API_TOKEN", "secret-token")
+        self.set_env("AAILAB_MACHINE_ID", "blade-01")
+
+        with self.patch_post(fake_post):
+            @notify("user@example.com")
+            def compute():
+                return 123
+
+            self.assertEqual(compute(), 123)
+
+        self.assertEqual(captured["url"], "http://example.test/api/notify")
+        self.assertEqual(captured["headers"]["X-API-TOKEN"], "secret-token")
+        self.assertEqual(
+            captured["json"],
+            {
+                "machine_id": "blade-01",
+                "task_name": "NotifyTests.test_notify_sends_success_payload.<locals>.compute",
+                "status": 0,
+                "emails": ["user@example.com"],
+            },
+        )
+        self.assertEqual(captured["timeout"], 15)
+
+    def test_notify_sends_exception_text_and_reraises(self):
+        captured = {}
+
+        class FakeResponse:
+            def raise_for_status(self):
+                return None
+
+        def fake_post(url, headers, json, timeout):
+            captured["json"] = json
+            return FakeResponse()
+
+        self.set_env("SERVER_NOTIFY", "http://example.test/api/notify")
+        self.set_env("API_TOKEN", "secret-token")
+        self.set_env("AAILAB_MACHINE_ID", "blade-01")
+
+        with self.patch_post(fake_post):
+            @notify("user@example.com")
+            def compute():
+                raise RuntimeError("boom")
+
+            with self.assertRaisesRegex(RuntimeError, "boom"):
+                compute()
+
+        self.assertEqual(captured["json"]["status"], "boom")
+        self.assertEqual(captured["json"]["emails"], ["user@example.com"])
+
+    def test_notify_supports_async_functions(self):
+        captured = {}
+
+        class FakeResponse:
+            def raise_for_status(self):
+                return None
+
+        def fake_post(url, headers, json, timeout):
+            captured["json"] = json
+            return FakeResponse()
+
+        self.set_env("SERVER_NOTIFY", "http://example.test/api/notify")
+        self.set_env("API_TOKEN", "secret-token")
+        self.set_env("AAILAB_MACHINE_ID", "blade-01")
+
+        with self.patch_post(fake_post):
+            @notify("user@example.com")
+            async def compute():
+                return "ok"
+
+            self.assertEqual(asyncio.run(compute()), "ok")
+
+        self.assertEqual(captured["json"]["status"], 0)
+
+    def test_notify_rejects_invalid_emails(self):
+        with self.assertRaisesRegex(ValueError, "invalid email"):
+            notify("invalid-email")