scitex-notification 0.1.0__py3-none-any.whl

scitex_notification/__init__.py

@@ -0,0 +1,321 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-03-16 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-notification/src/scitex_notification/__init__.py
+
+"""SciTeX Notification Module - User alerts and feedback.
+
+Usage:
+    import scitex_notification as stxn
+
+    # Simple alert - uses fallback priority (audio -> emacs -> desktop -> ...)
+    stxn.alert("2FA required!")
+
+    # Specify backend (no fallback)
+    stxn.alert("Error", backend="email")
+
+    # Multiple backends (tries all)
+    stxn.alert("Critical", backend=["audio", "email"])
+
+    # Use fallback explicitly
+    stxn.alert("Important", fallback=True)
+
+    # Make a phone call via Twilio
+    stxn.call("Critical alert!")
+
+    # Send an SMS via Twilio
+    stxn.sms("Build done!")
+
+Environment Variables:
+    SCITEX_NOTIFY_DEFAULT_BACKEND: audio, email, desktop, webhook
+    SCITEX_UI_DEFAULT_BACKEND: (deprecated) use SCITEX_NOTIFY_DEFAULT_BACKEND
+    SCITEX_NOTIFICATION_ENV_SRC: path to .env file to auto-load on import
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Optional, Union
+
+from ._env_loader import load_scitex_notification_env as _load_env
+
+_load_env()
+
+from ._backends import NotifyLevel as _AlertLevel
+from ._backends import available_backends as _available_backends
+from ._backends import get_backend as _get_backend
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "alert",
+    "alert_async",
+    "available_backends",
+    "call",
+    "call_async",
+    "sms",
+    "sms_async",
+    "__version__",
+]
+
+# Default fallback priority order
+DEFAULT_FALLBACK_ORDER = [
+    "audio",  # 1st: TTS audio (non-blocking, immediate)
+    "emacs",  # 2nd: Emacs minibuffer (if in Emacs)
+    "matplotlib",  # 3rd: Visual popup
+    "playwright",  # 4th: Browser popup
+    "email",  # 5th: Email (slowest, most reliable)
+]
+
+
+def available_backends() -> list[str]:
+    """Return list of available alert backends."""
+    return _available_backends()
+
+
+async def alert_async(
+    message: str,
+    title: Optional[str] = None,
+    backend: Optional[Union[str, list[str]]] = None,
+    level: str = "info",
+    fallback: bool = True,
+    **kwargs,
+) -> bool:
+    """Send alert asynchronously.
+
+    Parameters
+    ----------
+    message : str
+        Alert message
+    title : str, optional
+        Alert title
+    backend : str or list[str], optional
+        Backend(s) to use. If None, uses default with fallback.
+    level : str
+        Alert level: info, warning, error, critical
+    fallback : bool
+        If True and backend fails, try next in priority order.
+        Default True when backend=None, False when backend specified.
+
+    Returns
+    -------
+    bool
+        True if any backend succeeded
+    """
+    try:
+        lvl = _AlertLevel(level.lower())
+    except ValueError:
+        lvl = _AlertLevel.INFO
+
+    # Determine backends to try
+    if backend is None:
+        # No backend specified: use fallback priority
+        default = (
+            os.getenv("SCITEX_NOTIFICATION_DEFAULT_BACKEND")
+            or os.getenv("SCITEX_NOTIFY_DEFAULT_BACKEND")
+            or os.getenv("SCITEX_UI_DEFAULT_BACKEND", "audio")
+        )
+        if fallback:
+            # Start with default, then try others in priority order
+            backends = [default] + [b for b in DEFAULT_FALLBACK_ORDER if b != default]
+        else:
+            backends = [default]
+    else:
+        # Backend specified: use it (with optional fallback)
+        backends = [backend] if isinstance(backend, str) else list(backend)
+        if fallback and len(backends) == 1:
+            # Add fallback backends after the specified one
+            backends = backends + [
+                b for b in DEFAULT_FALLBACK_ORDER if b not in backends
+            ]
+
+    # Try backends until one succeeds
+    available = _available_backends()
+    for name in backends:
+        if name not in available:
+            continue
+        try:
+            b = _get_backend(name)
+            result = await b.send(message, title=title, level=lvl, **kwargs)
+            if result.success:
+                return True
+        except Exception:
+            pass
+
+    return False
+
+
+def alert(
+    message: str,
+    title: Optional[str] = None,
+    backend: Optional[Union[str, list[str]]] = None,
+    level: str = "info",
+    fallback: bool = True,
+    **kwargs,
+) -> bool:
+    """Send alert synchronously.
+
+    Parameters
+    ----------
+    message : str
+        Alert message
+    title : str, optional
+        Alert title
+    backend : str or list[str], optional
+        Backend(s) to use. If None, uses fallback priority order.
+    level : str
+        Alert level: info, warning, error, critical
+    fallback : bool
+        If True and backend fails, try next in priority order.
+
+    Returns
+    -------
+    bool
+        True if any backend succeeded
+
+    Fallback Order
+    --------------
+    1. audio      - TTS (fast, non-blocking)
+    2. emacs      - Minibuffer message
+    3. matplotlib - Visual popup
+    4. playwright - Browser popup
+    5. email      - Email (slowest)
+    """
+    try:
+        asyncio.get_running_loop()
+        import concurrent.futures
+
+        with concurrent.futures.ThreadPoolExecutor() as executor:
+            future = executor.submit(
+                asyncio.run,
+                alert_async(message, title, backend, level, fallback, **kwargs),
+            )
+            return future.result(timeout=30)
+    except RuntimeError:
+        return asyncio.run(
+            alert_async(message, title, backend, level, fallback, **kwargs)
+        )
+
+
+def call(
+    message: str,
+    title: Optional[str] = None,
+    level: str = "info",
+    to_number: Optional[str] = None,
+    **kwargs,
+) -> bool:
+    """Make a phone call via Twilio.
+
+    Convenience wrapper for alert(backend="twilio").
+    """
+    return alert(
+        message,
+        title=title,
+        backend="twilio",
+        level=level,
+        fallback=False,
+        to_number=to_number,
+        **kwargs,
+    )
+
+
+async def call_async(
+    message: str,
+    title: Optional[str] = None,
+    level: str = "info",
+    to_number: Optional[str] = None,
+    **kwargs,
+) -> bool:
+    """Make a phone call via Twilio (async)."""
+    return await alert_async(
+        message,
+        title=title,
+        backend="twilio",
+        level=level,
+        fallback=False,
+        to_number=to_number,
+        **kwargs,
+    )
+
+
+async def sms_async(
+    message: str,
+    title: Optional[str] = None,
+    to_number: Optional[str] = None,
+    **kwargs,
+) -> bool:
+    """Send an SMS via Twilio (async).
+
+    Parameters
+    ----------
+    message : str
+        SMS body text
+    title : str, optional
+        Prepended to message if provided
+    to_number : str, optional
+        Override SCITEX_NOTIFY_TWILIO_TO
+
+    Returns
+    -------
+    bool
+        True if SMS sent successfully
+    """
+    from ._backends._twilio import send_sms as _send_sms
+
+    result = await _send_sms(
+        message,
+        title=title,
+        to_number=to_number,
+        **kwargs,
+    )
+    return result.success
+
+
+def sms(
+    message: str,
+    title: Optional[str] = None,
+    to_number: Optional[str] = None,
+    **kwargs,
+) -> bool:
+    """Send an SMS via Twilio.
+
+    Parameters
+    ----------
+    message : str
+        SMS body text
+    title : str, optional
+        Prepended to message if provided
+    to_number : str, optional
+        Override SCITEX_NOTIFY_TWILIO_TO
+
+    Returns
+    -------
+    bool
+        True if SMS sent successfully
+    """
+    try:
+        asyncio.get_running_loop()
+        import concurrent.futures
+
+        with concurrent.futures.ThreadPoolExecutor() as executor:
+            future = executor.submit(
+                asyncio.run,
+                sms_async(message, title, to_number, **kwargs),
+            )
+            return future.result(timeout=30)
+    except RuntimeError:
+        return asyncio.run(sms_async(message, title, to_number, **kwargs))
+
+
+# Apply @supports_return_as decorator if scitex_dev is available
+try:
+    from scitex_dev.decorators import supports_return_as as _supports_return_as
+
+    alert = _supports_return_as(alert)
+    call = _supports_return_as(call)
+    sms = _supports_return_as(sms)
+except ImportError:
+    pass
+
+
+# EOF

scitex_notification/__main__.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+"""Allow running scitex-notification as: python -m scitex_notification."""
+
+from scitex_notification._cli import main
+
+if __name__ == "__main__":
+    main()

scitex_notification/_backends/__init__.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-13 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-notification/src/scitex_notification/_backends/__init__.py
+
+"""Notification backend registry and utilities."""
+
+from __future__ import annotations
+
+from ._audio import AudioBackend
+from ._desktop import DesktopBackend
+from ._emacs import EmacsBackend
+from ._email import EmailBackend
+from ._matplotlib import MatplotlibBackend
+from ._playwright import PlaywrightBackend
+from ._twilio import TwilioBackend
+from ._types import BaseNotifyBackend, NotifyLevel, NotifyResult
+from ._webhook import WebhookBackend
+
+__all__ = [
+    "NotifyLevel",
+    "NotifyResult",
+    "BaseNotifyBackend",
+    "AudioBackend",
+    "EmailBackend",
+    "DesktopBackend",
+    "EmacsBackend",
+    "WebhookBackend",
+    "MatplotlibBackend",
+    "PlaywrightBackend",
+    "TwilioBackend",
+    "BACKENDS",
+    "get_backend",
+    "available_backends",
+]
+
+# Registry of available backends
+BACKENDS: dict[str, type[BaseNotifyBackend]] = {
+    "audio": AudioBackend,
+    "email": EmailBackend,
+    "desktop": DesktopBackend,
+    "emacs": EmacsBackend,
+    "webhook": WebhookBackend,
+    "matplotlib": MatplotlibBackend,
+    "playwright": PlaywrightBackend,
+    "twilio": TwilioBackend,
+}
+
+
+def get_backend(name: str, **kwargs) -> BaseNotifyBackend:
+    """Get a notification backend by name."""
+    if name not in BACKENDS:
+        raise ValueError(f"Unknown backend: {name}. Available: {list(BACKENDS.keys())}")
+    return BACKENDS[name](**kwargs)
+
+
+def available_backends() -> list[str]:
+    """Return list of available notification backends."""
+    available = []
+    for name, cls in BACKENDS.items():
+        try:
+            backend = cls()
+            if backend.is_available():
+                available.append(name)
+        except Exception:
+            pass
+    return available
+
+
+# EOF

scitex_notification/_backends/_audio.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-13 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-notification/src/scitex_notification/_backends/_audio.py
+
+"""Audio notification backend via TTS."""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+from typing import Optional
+
+from ._types import BaseNotifyBackend, NotifyLevel, NotifyResult
+
+try:
+    from scitex_audio import available_backends as _audio_available_backends
+    from scitex_audio import speak as _audio_speak
+
+    _AUDIO_AVAILABLE = True
+except ImportError:
+    _AUDIO_AVAILABLE = False
+    _audio_speak = None
+    _audio_available_backends = None
+
+
+class AudioBackend(BaseNotifyBackend):
+    """Audio notification via scitex_audio TTS."""
+
+    name = "audio"
+
+    def __init__(
+        self,
+        backend: str = "gtts",
+        speed: float = 1.5,
+        rate: int = 180,
+    ):
+        self.tts_backend = backend
+        self.speed = speed
+        self.rate = rate
+
+    def is_available(self) -> bool:
+        if not _AUDIO_AVAILABLE:
+            return False
+        try:
+            return len(_audio_available_backends()) > 0
+        except Exception:
+            return False
+
+    async def send(
+        self,
+        message: str,
+        title: Optional[str] = None,
+        level: NotifyLevel = NotifyLevel.INFO,
+        **kwargs,
+    ) -> NotifyResult:
+        try:
+            if not _AUDIO_AVAILABLE or _audio_speak is None:
+                raise ImportError(
+                    "scitex_audio is not installed. "
+                    "Install it with: pip install scitex-audio"
+                )
+
+            # Prepend title if provided
+            full_message = f"{title}. {message}" if title else message
+
+            # Add urgency prefix for critical/error levels
+            if level == NotifyLevel.CRITICAL:
+                full_message = f"Critical alert! {full_message}"
+            elif level == NotifyLevel.ERROR:
+                full_message = f"Error. {full_message}"
+
+            # Run TTS in executor to not block
+            loop = asyncio.get_event_loop()
+            await loop.run_in_executor(
+                None,
+                lambda: _audio_speak(
+                    full_message,
+                    backend=kwargs.get("tts_backend", self.tts_backend),
+                    speed=kwargs.get("speed", self.speed),
+                    rate=kwargs.get("rate", self.rate),
+                ),
+            )
+
+            return NotifyResult(
+                success=True,
+                backend=self.name,
+                message=message,
+                timestamp=datetime.now().isoformat(),
+            )
+        except Exception as e:
+            return NotifyResult(
+                success=False,
+                backend=self.name,
+                message=message,
+                timestamp=datetime.now().isoformat(),
+                error=str(e),
+            )
+
+
+# EOF