scitex_notification
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_NOTIFICATION_DEFAULT_BACKEND: audio, email, desktop, webhook SCITEX_NOTIFICATION_ENV_SRC: path to .env file to auto-load on import
- scitex_notification.alert(message: str, title: str | None = None, backend: str | list[str] | None = None, level: str = 'info', fallback: bool | None = None, **kwargs) bool[source]
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, walks the fallback priority order. A single explicit backend is used on its own (no silent substitution) unless
fallback=Trueis passed.level (str) – Alert level: info, warning, error, critical
fallback (bool, optional) – If None (default) resolves to
backend is None— an explicit backend never silently falls back. Seealert_async().
- Returns:
True if the requested backend(s) delivered the alert.
- Return type:
- Raises:
ValueError / RuntimeError – When a single explicit backend (fallback disabled) is unavailable or fails — see
alert_async(). The fallback path (backend=None) still returnsFalseon total failure.Fallback Order –
-------------- –
1. audio - TTS (fast, non-blocking) –
2. emacs - Minibuffer message –
3. matplotlib - Visual popup –
4. playwright - Browser popup –
5. email - Email (slowest) –
- async scitex_notification.alert_async(message: str, title: str | None = None, backend: str | list[str] | None = None, level: str = 'info', fallback: bool | None = None, **kwargs) bool[source]
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, walks the default fallback priority order. If a single backend name is given, ONLY that backend is used (no silent substitution) unless
fallback=Trueis passed explicitly.level (str) – Alert level: info, warning, error, critical
fallback (bool, optional) – Controls whether other backends are tried after the requested one(s). If left as
None(default), it resolves tobackend is None— i.e. an EXPLICIT backend request fails loud rather than silently falling through to another channel (no-silent-fallbacks policy). PassTrueto opt back into fallback for an explicit backend, orFalseto forbid it even whenbackend is None.
- Returns:
True if the requested backend(s) delivered the alert.
- Return type:
- Raises:
ValueError – If a single explicit backend is requested with fallback disabled and that backend is not currently available — the caller asked for a specific channel that cannot fire, so we fail loud instead of returning a quiet
Falsethat looks like a transient send failure.
- scitex_notification.available_backends() list[str][source]
Return list of available alert backends.
- scitex_notification.call(message: str, title: str | None = None, level: str = 'info', to_number: str | None = None, **kwargs) bool[source]
Make a phone call via Twilio.
Convenience wrapper for alert(backend=”twilio”).
- async scitex_notification.call_async(message: str, title: str | None = None, level: str = 'info', to_number: str | None = None, **kwargs) bool[source]
Make a phone call via Twilio (async).
- scitex_notification.notify(subject: str = '', message: str = ':)', file: str | None = None, ID: str = 'auto', sender_name: str | None = None, recipient_email: str | None = None, cc: str | list | None = None, attachment_paths: list | None = None, verbose: bool = False) None[source]
Send a script-aware notification email.
Builds a subject/body from the calling script’s name and appends a footer with host, script, package version and git branch, then delegates to
send_gmail().Credentials and recipient are read from environment variables (with backward-compatible aliases):
sender:
SCITEX_SCHOLAR_EMAIL_NOREPLY/SCITEX_SCHOLAR_FROM_EMAIL_ADDRESS/SCITEX_EMAIL_NOREPLY/SCITEX_EMAIL_AGENT(defaultno-reply@scitex.ai)password:
SCITEX_SCHOLAR_EMAIL_PASSWORD/SCITEX_SCHOLAR_FROM_EMAIL_PASSWORD/SCITEX_EMAIL_PASSWORDrecipient:
SCITEX_SCHOLAR_EMAIL_RECIPIENT/SCITEX_SCHOLAR_TO_EMAIL_ADDRESS(or passrecipient_email=)
- scitex_notification.send_gmail(sender_gmail: str, sender_password: str, recipient_email: str, subject: str, message: str, sender_name: str | None = None, cc: str | list | None = None, ID: str | None = None, attachment_paths: list | None = None, verbose: bool = True, smtp_server: str | None = None, smtp_port: int | None = None) None[source]
Send an email via SMTP.
Despite the name, supports any SMTP server. Uses
mail1030.onamae.ne.jpby default (for scitex.ai emails) and falls back to Gmail’s server when the sender address ends in@gmail.com.- Parameters:
sender_gmail (str) – Sender email address (and SMTP login).
sender_password (str) – SMTP password.
recipient_email (str) – Primary recipient address.
subject (str) – Email subject. If
IDis given it is appended as(ID: ...).message (str) – Plain-text body.
sender_name (str, optional) – Display name for the
Fromheader.ID (str, optional) – Message ID. Pass
"auto"to auto-generate one.attachment_paths (list, optional) – Paths of files to attach.
.logfiles are ANSI-stripped.verbose (bool) – Print a confirmation line on success.
smtp_server (optional) – Override SMTP host/port auto-detection.
smtp_port (optional) – Override SMTP host/port auto-detection.
- scitex_notification.sms(message: str, title: str | None = None, to_number: str | None = None, **kwargs) bool[source]
Send an SMS via Twilio.