Get a notification when your Python script finishes or crashes

Wrap the script so every exit sends a message

A notify() call on the last line only covers the happy path. When a scraper hits bad HTML or an ETL job dies two hours in, the exception aborts the run before that line executes, which is exactly when you needed the ping.

Wrap your main() call in try/except/finally instead. The finally block runs whether the script finishes cleanly or blows up (including Ctrl-C), so one notify() call covers both outcomes. Catch the exception to grab its text, re-raise it so you keep the traceback and the non-zero exit code, and put the elapsed time in the message.

import time

if __name__ == "__main__":
    started = time.monotonic()
    error = None
    try:
        main()
    except BaseException as exc:
        if not (isinstance(exc, SystemExit) and exc.code in (0, None)):
            error = exc
        raise
    finally:
        minutes = (time.monotonic() - started) / 60
        if error is None:
            notify(f"nightly.py finished in {minutes:.0f}m")
        else:
            notify(f"nightly.py failed after {minutes:.0f}m: {error!r}")

You can also register a cleanup function with the atexit module. It runs at normal interpreter shutdown without re-indenting your entrypoint, but getting the exception details out of it is clunky compared to a plain try/except.

Neither finally nor atexit catches everything. The Python docs note that atexit handlers are not called when the program is killed by a signal not handled by Python, when a fatal internal error is detected, or when os._exit() is called, and finally has the same blind spots:

• SIGKILL (kill -9 or the Linux out-of-memory killer) ends the process from the kernel side, with no chance to run cleanup code.
• os._exit() terminates right away without unwinding the stack.
• A fatal error in the interpreter itself aborts straight out.

A plain SIGTERM (what kill and docker stop send first) also skips both unless you catch it. Install a tiny handler that calls sys.exit(143): it turns the signal into a SystemExit exception that unwinds the stack and triggers your finally block.

import signal
import sys

signal.signal(signal.SIGTERM, lambda signum, frame: sys.exit(143))

Choose where the message goes

Your notify(text) function only needs to make one outbound call. Pick whichever app you already keep open:

• Discord webhook: create a webhook in a channel's settings, then POST JSON {"content": "..."} to its URL. See the Discord webhook guide.
• Slack incoming webhook: enable incoming webhooks in a Slack app, pick a channel and POST JSON {"text": "..."}.
• Telegram bot: get a bot token from @BotFather, find your chat_id and POST both to sendMessage.
• ntfy: install the free Android or iOS app, subscribe to a topic name you make up and POST the message body to https://ntfy.sh/<topic>.
• Email through Gmail: turn on 2-Step Verification, create an app password and send through smtp.gmail.com on port 465 over SSL.

The first four are plain HTTP POST requests. Pass timeout=10 on each call, and catch errors inside notify() so a flaky network at the end of a job never hides the job's own traceback.

import os
import sys

import requests


def notify_discord(text):
    url = os.environ["DISCORD_WEBHOOK_URL"]
    requests.post(url, json={"content": text[:2000]}, timeout=10).raise_for_status()


def notify_slack(text):
    url = os.environ["SLACK_WEBHOOK_URL"]
    requests.post(url, json={"text": text}, timeout=10).raise_for_status()


def notify_telegram(text):
    url = f"https://api.telegram.org/bot{os.environ['TELEGRAM_BOT_TOKEN']}/sendMessage"
    payload = {"chat_id": os.environ["TELEGRAM_CHAT_ID"], "text": text[:4096]}
    requests.post(url, json=payload, timeout=10).raise_for_status()


def notify_ntfy(text):
    url = f"https://ntfy.sh/{os.environ['NTFY_TOPIC']}"
    requests.post(url, data=text.encode("utf-8"), timeout=10).raise_for_status()


def notify(text):
    try:
        notify_discord(text)
    except Exception as exc:
        print(f"notification failed: {exc!r}", file=sys.stderr)

For email without extra dependencies, the standard library smtplib connects to smtp.gmail.com:465 over SSL with your Gmail address and the app password.

import os
import smtplib
from email.message import EmailMessage


def notify_email(text):
    msg = EmailMessage()
    msg["Subject"] = text.splitlines()[0][:80]
    msg["From"] = os.environ["GMAIL_ADDRESS"]
    msg["To"] = os.environ["GMAIL_ADDRESS"]
    msg.set_content(text)
    with smtplib.SMTP_SSL("smtp.gmail.com", 465, timeout=10) as smtp:
        smtp.login(os.environ["GMAIL_ADDRESS"], os.environ["GMAIL_APP_PASSWORD"])
        smtp.send_message(msg)

Desktop notifications on the same machine

When the job runs on the laptop in front of you and the terminal is buried under browser windows, you don't need a webhook. Call notify-send on Linux or osascript on macOS through subprocess.run to pop a native banner.

These only work on the machine you're sitting at. notify-send needs an active desktop session, so inside an SSH session on a remote server it fails with Cannot autolaunch D-Bus without X11 $DISPLAY. For remote boxes, use one of the phone channels above.

import platform
import subprocess


def notify_desktop(title, body):
    if platform.system() == "Darwin":
        script = f'display notification "{body}" with title "{title}"'
        subprocess.run(["osascript", "-e", script], check=False)
    else:
        subprocess.run(["notify-send", title, body], check=False)

Hangs never reach your finally block

Everything above assumes the script actually finishes or crashes. A script that hangs (a network call with no timeout, a deadlock, a stuck worker) never exits, so no finally block or atexit handler runs and you get no message at all.

HTTP calls are a common culprit: requests has no default timeout, and its docs warn that a missing timeout "can cause your program to hang indefinitely". The GNU timeout command puts a hard ceiling on the whole run and exits with status 124 when it fires. For more ways to spot a hang, see how to tell if a Python script is stuck.