aailab-tools 0.1.0__py3-none-any.whl

aailab_tools/__init__.py

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

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,6 @@
+aailab_tools/__init__.py,sha256=u-c8VLuPZ759xPQyQzuhs1dNX0C1uBAKUQnkoOfCjR8,49
+aailab_tools/notify.py,sha256=9eKTU2QfT0sFAyUEiriIQDb7at2tlFR7lWQaBS0A7LI,2838
+aailab_tools-0.1.0.dist-info/METADATA,sha256=zdJ01UfNWg1qBXnTZj6t64aTTBz7iBVaySkQx32qUP8,1592
+aailab_tools-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+aailab_tools-0.1.0.dist-info/top_level.txt,sha256=Lv0wE00Ow-NQnHEanG8hnYgjWgc8z1Qh2IvnkCcFesc,13
+aailab_tools-0.1.0.dist-info/RECORD,,

aailab_tools-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

aailab_tools-0.1.0.dist-info/top_level.txt

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