{"course":{"slug":"python-for-ai","title":"Python, from Zero, for AI","url":"https://addaly.com/learn/python-for-ai","level":"beginner","track":"build"},"lesson":{"slug":"scheduling-and-idempotent-jobs","title":"Running it every morning: cron, a lock file, and a job that is safe to run twice","url":"https://addaly.com/learn/python-for-ai/scheduling-and-idempotent-jobs","position":88,"of":89,"minutes":9,"answer":"A scheduler only starts the process; the job must find its own environment, refuse to run alongside itself, record what it has already processed so a re-run does no harm.","keyIdea":"A scheduler only starts the process; the job must find its own environment, refuse to run alongside itself, record what it has already processed so a re-run does no harm, and write logs somewhere a person will read them."},"body":{"format":"markdown","text":"## The scheduler does very little\n\nA scheduler starts your program at a time. That is all. Everything else (where it runs, what it can see, what happens if it is still running when the next start arrives, what happens if it runs twice) is your program's problem, and a script that works perfectly by hand fails under a scheduler for exactly those reasons.\n\n## cron, and the free alternatives\n\nOn macOS and Linux, `crontab -e` opens a file of lines:\n\n```\n# minute hour day month weekday   command\n0 7 * * *   cd /home/asha/tagger && /home/asha/tagger/.venv/bin/python -m tagger.daily >> logs/daily.log 2>&1\n```\n\nFive time fields, then the command. `0 7 * * *` is seven every morning. `*/15 * * * *` is every fifteen minutes. The site `crontab.guru` decodes any line.\n\nThree things in that command are deliberate. The `cd` sets the working directory, because cron starts in your home folder and module 5's relative paths will be wrong otherwise. The **full path to the venv's Python** selects the right interpreter and packages, because cron's `PATH` is nearly empty and `python` may resolve to nothing or to the system's. And `>> logs/daily.log 2>&1` captures stdout and stderr to a file, because cron's output otherwise goes to a local mail spool nobody reads.\n\nWindows has Task Scheduler with the same shape; macOS also has `launchd`, which survives the machine being asleep at the scheduled minute better than cron does. And GitHub Actions, in the next lesson, has an `on: schedule:` trigger with cron syntax that runs your job on their machines for free: the right choice for a job that should run even when your laptop is closed.\n\n## The environment is not yours\n\nCron does not read `~/.zshrc`, `~/.bashrc` or `~/.zprofile`. Every variable you exported there (the API key, the database URL) is absent. The script fails with `KeyError` on the variable name, or worse, runs with a default and processes nothing.\n\nModule 5 gave the fix: the job loads its own configuration. A `.env` file read by `load_dotenv()` at the top of `main()`, with its path derived from `__file__` so the working directory does not matter. Or a line in the crontab itself: `OPENAI_API_KEY=...` above the schedule lines, though that puts the key in a file with wide read permissions on some systems, and the `.env` is better. Print `bool(os.getenv(\"OPENAI_API_KEY\"))` as the first log line so a missing key is the first thing the log says.\n\n## Refusing to overlap\n\nA job scheduled every fifteen minutes that takes twenty will run alongside itself, two copies processing the same items and doubling the bill. A lock file prevents it:\n\n```python\nimport fcntl, sys\n\ndef main():\n    lock = open(\"/tmp/tagger-daily.lock\", \"w\")\n    try:\n        fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)\n    except BlockingIOError:\n        log.warning(\"previous run still active; exiting\")\n        return 0\n    run()\n```\n\n`flock` with `LOCK_NB` takes an exclusive lock or fails immediately. The operating system releases it when the process ends, even if it crashes, which a \"create a file, delete it at the end\" scheme does not, leaving a stale file that blocks every future run after one crash. On Windows, `msvcrt.locking` does the same; the `filelock` package (free) wraps both.\n\n## Safe to run twice\n\nSooner or later a job will run twice on the same data: the scheduler fires twice, you re-run it by hand after a partial failure, a machine restarts. A job that re-posts every summary, re-sends every email, or re-charges every call on the second run is a job you cannot safely retry, and one you cannot retry is one you cannot fix.\n\nThe property to design for is **idempotency**: module 6's word, applied to your own program: running it again produces the same final state, not twice the effects. The mechanism is a record of what has been done:\n\n```python\ndef run():\n    done = load_done_ids(\"state/done.json\")          # or a sqlite table\n    for msg in fetch_new_messages():\n        if msg.id in done:\n            continue\n        summary = summarise(msg)\n        post(summary, idempotency_key=msg.id)\n        done.add(msg.id)\n        save_done_ids(done)                          # after each item, not at the end\n```\n\nRecord each item as it completes, so a crash at item 30 of 50 resumes at 31. Pass the item's ID as an idempotency key to anything that accepts one, so even a duplicate `post` is absorbed at the far end. Make the record the source of truth about what is done, never the log.\n\nThe module-6 cache helps here too: a re-run that hits the cache for every already-summarised message costs nothing even if the done-record is lost.\n\n## Exit codes and logs\n\nReturn `0` on success and non-zero on failure from `main()`, and let module 3's `sys.exit(main())` carry it out. Schedulers and CI record the code; it is how \"did it work\" becomes a query rather than a search through logs.\n\nLog to a file, with rotation, so a job that runs for a year does not fill the disk:\n\n```python\nfrom logging.handlers import RotatingFileHandler\nhandler = RotatingFileHandler(\"logs/daily.log\", maxBytes=5_000_000, backupCount=5)\n```\n\nLog one line at start with the timestamp and configuration, one per item at `INFO`, and one at the end with counts: processed, skipped, failed, and the total cost from module 6's `Budget`. A job whose last line is `done: 48 processed, 2 failed, $0.31` is a job you can check in five seconds.\n\n## When it silently stops\n\nThe worst failure is the job that stopped running three weeks ago and nobody noticed. The cheap defence is a heartbeat: the job's last act is to write the current time to a file or hit a URL, and something else (a second tiny cron line, a free monitoring service) alerts when the heartbeat is older than expected. This is the one addition that turns a script into something you can stop watching.\n\n## Try this now\n\nPut your summariser under cron every two minutes with the venv path and log redirection. Watch it fail on the missing key, fix it with `.env`, then make the job take three minutes and watch the lock reject the overlap. Finally, run it twice by hand and confirm the second run posts nothing."},"check":{"question":"A script that summarises new messages and posts the summary works when run by hand. Under cron it fails with `KeyError: 'OPENAI_API_KEY'`. Which explanation fits and which fix follows?","options":[{"text":"Cron runs the script as a different system user who has no permission to read another user's environment variables, so the script must be given `sudo` or run as root.","correct":false,"tempting":"Cron typically runs as the same user; the issue is which shell files are read, not permissions, and `sudo` would widen access for no reason."},{"text":"Cron scripts cannot make network calls, so the API client fails at import and reports a missing key.","correct":false,"tempting":"Cron places no restriction on networking; the error names the environment variable and is raised before any call."},{"text":"Cron starts jobs with a minimal environment that never reads the shell profile, so the job must load its own configuration or the crontab must set it.","correct":true},{"text":"The key was set with `export` in the terminal, which is case-sensitive, and cron lowercases environment variable names.","correct":false,"tempting":"Cron does not alter variable names; the variable is simply not present in the environment cron provides."}]},"prev":{"slug":"an-endpoint-with-fastapi","title":"An HTTP endpoint with FastAPI: your function, callable by any program","url":"https://addaly.com/learn/python-for-ai/an-endpoint-with-fastapi"},"next":{"slug":"github-actions-ci","title":"GitHub Actions: the tests run on a machine that is not yours, before anything ships","url":"https://addaly.com/learn/python-for-ai/github-actions-ci"},"authorship":"Founder and series editor: Dr Mustafa Mun. Written by AI models to a written standard. Source and assessment review continues. Academic review invited.","review":{"status":"Draft, open for academic review"},"cite":"Addaly (2026) 'Running it every morning: cron, a lock file, and a job that is safe to run twice', in Python, from Zero, for AI. Edited by M. Mun. Addaly. Available at: https://addaly.com/learn/python-for-ai/scheduling-and-idempotent-jobs (Accessed: 21 November 2026).","licence":{"name":"CC BY-NC-SA 4.0","url":"https://creativecommons.org/licenses/by-nc-sa/4.0/"},"reader":{"schema":1,"title":"Running it every morning: cron, a lock file, and a job that is safe to run twice","courseTitle":"Python, from Zero, for AI","module":{"index":9,"slug":"building-the-thing","title":"Building the thing: a small AI program, end to end"},"answer":null,"keyIdea":"A scheduler only starts the process; the job must find its own environment, refuse to run alongside itself, record what it has already processed so a re-run does no harm, and write logs somewhere a person will read them.","hero":{"kind":"plate","image":null,"alt":null,"caption":null},"blocks":[{"t":"h2","id":"the-scheduler-does-very-little","runs":[{"text":"The scheduler does very little"}]},{"t":"p","runs":[{"text":"A scheduler starts your program at a time. That is all. Everything else (where it runs, what it can see, what happens if it is still running when the next start arrives, what happens if it runs twice) is your program’s problem, and a script that works perfectly by hand fails under a scheduler for exactly those reasons."}]},{"t":"h2","id":"cron-and-the-free-alternatives","runs":[{"text":"cron, and the free alternatives"}]},{"t":"p","runs":[{"text":"On macOS and Linux, "},{"text":"crontab -e","code":true},{"text":" opens a file of lines:"}]},{"t":"code","lang":"","label":"Text","text":"# minute hour day month weekday   command\n0 7 * * *   cd /home/asha/tagger && /home/asha/tagger/.venv/bin/python -m tagger.daily >> logs/daily.log 2>&1"},{"t":"p","runs":[{"text":"Five time fields, then the command. "},{"text":"0 7 * * *","code":true},{"text":" is seven every morning. "},{"text":"*/15 * * * *","code":true},{"text":" is every fifteen minutes. The site "},{"text":"crontab.guru","code":true},{"text":" decodes any line."}]},{"t":"p","runs":[{"text":"Three things in that command are deliberate. The "},{"text":"cd","code":true},{"text":" sets the working directory, because cron starts in your home folder and module 5’s relative paths will be wrong otherwise. The "},{"text":"full path to the venv’s Python","b":true},{"text":" selects the right interpreter and packages, because cron’s "},{"text":"PATH","code":true},{"text":" is nearly empty and "},{"text":"python","code":true},{"text":" may resolve to nothing or to the system’s. And "},{"text":">> logs/daily.log 2>&1","code":true},{"text":" captures stdout and stderr to a file, because cron’s output otherwise goes to a local mail spool nobody reads."}]},{"t":"p","runs":[{"text":"Windows has Task Scheduler with the same shape; macOS also has "},{"text":"launchd","code":true},{"text":", which survives the machine being asleep at the scheduled minute better than cron does. And GitHub Actions, in the next lesson, has an "},{"text":"on: schedule:","code":true},{"text":" trigger with cron syntax that runs your job on their machines for free: the right choice for a job that should run even when your laptop is closed."}]},{"t":"h2","id":"the-environment-is-not-yours","runs":[{"text":"The environment is not yours"}]},{"t":"p","runs":[{"text":"Cron does not read "},{"text":"~/.zshrc","code":true},{"text":", "},{"text":"~/.bashrc","code":true},{"text":" or "},{"text":"~/.zprofile","code":true},{"text":". Every variable you exported there (the API key, the database URL) is absent. The script fails with "},{"text":"KeyError","code":true},{"text":" on the variable name, or worse, runs with a default and processes nothing."}]},{"t":"p","runs":[{"text":"Module 5 gave the fix: the job loads its own configuration. A "},{"text":".env","code":true},{"text":" file read by "},{"text":"load_dotenv()","code":true},{"text":" at the top of "},{"text":"main()","code":true},{"text":", with its path derived from "},{"text":"__file__","code":true},{"text":" so the working directory does not matter. Or a line in the crontab itself: "},{"text":"OPENAI_API_KEY=...","code":true},{"text":" above the schedule lines, though that puts the key in a file with wide read permissions on some systems, and the "},{"text":".env","code":true},{"text":" is better. Print "},{"text":"bool(os.getenv(\"OPENAI_API_KEY\"))","code":true},{"text":" as the first log line so a missing key is the first thing the log says."}]},{"t":"h2","id":"refusing-to-overlap","runs":[{"text":"Refusing to overlap"}]},{"t":"p","runs":[{"text":"A job scheduled every fifteen minutes that takes twenty will run alongside itself, two copies processing the same items and doubling the bill. A lock file prevents it:"}]},{"t":"code","lang":"python","label":"Python","text":"import fcntl, sys\n\ndef main():\n    lock = open(\"/tmp/tagger-daily.lock\", \"w\")\n    try:\n        fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)\n    except BlockingIOError:\n        log.warning(\"previous run still active; exiting\")\n        return 0\n    run()"},{"t":"p","runs":[{"text":"flock","code":true},{"text":" with "},{"text":"LOCK_NB","code":true},{"text":" takes an exclusive lock or fails immediately. The operating system releases it when the process ends, even if it crashes, which a “create a file, delete it at the end” scheme does not, leaving a stale file that blocks every future run after one crash. On Windows, "},{"text":"msvcrt.locking","code":true},{"text":" does the same; the "},{"text":"filelock","code":true},{"text":" package (free) wraps both."}]},{"t":"h2","id":"safe-to-run-twice","runs":[{"text":"Safe to run twice"}]},{"t":"p","runs":[{"text":"Sooner or later a job will run twice on the same data: the scheduler fires twice, you re-run it by hand after a partial failure, a machine restarts. A job that re-posts every summary, re-sends every email, or re-charges every call on the second run is a job you cannot safely retry, and one you cannot retry is one you cannot fix."}]},{"t":"p","runs":[{"text":"The property to design for is "},{"text":"idempotency","b":true},{"text":": module 6’s word, applied to your own program: running it again produces the same final state, not twice the effects. The mechanism is a record of what has been done:"}]},{"t":"code","lang":"python","label":"Python","text":"def run():\n    done = load_done_ids(\"state/done.json\")          # or a sqlite table\n    for msg in fetch_new_messages():\n        if msg.id in done:\n            continue\n        summary = summarise(msg)\n        post(summary, idempotency_key=msg.id)\n        done.add(msg.id)\n        save_done_ids(done)                          # after each item, not at the end"},{"t":"p","runs":[{"text":"Record each item as it completes, so a crash at item 30 of 50 resumes at 31. Pass the item’s ID as an idempotency key to anything that accepts one, so even a duplicate "},{"text":"post","code":true},{"text":" is absorbed at the far end. Make the record the source of truth about what is done, never the log."}]},{"t":"p","runs":[{"text":"The module-6 cache helps here too: a re-run that hits the cache for every already-summarised message costs nothing even if the done-record is lost."}]},{"t":"h2","id":"exit-codes-and-logs","runs":[{"text":"Exit codes and logs"}]},{"t":"p","runs":[{"text":"Return "},{"text":"0","code":true},{"text":" on success and non-zero on failure from "},{"text":"main()","code":true},{"text":", and let module 3’s "},{"text":"sys.exit(main())","code":true},{"text":" carry it out. Schedulers and CI record the code; it is how “did it work” becomes a query rather than a search through logs."}]},{"t":"p","runs":[{"text":"Log to a file, with rotation, so a job that runs for a year does not fill the disk:"}]},{"t":"code","lang":"python","label":"Python","text":"from logging.handlers import RotatingFileHandler\nhandler = RotatingFileHandler(\"logs/daily.log\", maxBytes=5_000_000, backupCount=5)"},{"t":"p","runs":[{"text":"Log one line at start with the timestamp and configuration, one per item at "},{"text":"INFO","code":true},{"text":", and one at the end with counts: processed, skipped, failed, and the total cost from module 6’s "},{"text":"Budget","code":true},{"text":". A job whose last line is "},{"text":"done: 48 processed, 2 failed, $0.31","code":true},{"text":" is a job you can check in five seconds."}]},{"t":"h2","id":"when-it-silently-stops","runs":[{"text":"When it silently stops"}]},{"t":"p","runs":[{"text":"The worst failure is the job that stopped running three weeks ago and nobody noticed. The cheap defence is a heartbeat: the job’s last act is to write the current time to a file or hit a URL, and something else (a second tiny cron line, a free monitoring service) alerts when the heartbeat is older than expected. This is the one addition that turns a script into something you can stop watching."}]},{"t":"h2","id":"try-this-now","runs":[{"text":"Try this now"}],"role":"try"},{"t":"p","runs":[{"text":"Put your summariser under cron every two minutes with the venv path and log redirection. Watch it fail on the missing key, fix it with "},{"text":".env","code":true},{"text":", then make the job take three minutes and watch the lock reject the overlap. Finally, run it twice by hand and confirm the second run posts nothing."}]}],"check":{"question":[{"text":"A script that summarises new messages and posts the summary works when run by hand. Under cron it fails with "},{"text":"KeyError: 'OPENAI_API_KEY'","code":true},{"text":". Which explanation fits and which fix follows?"}],"options":[{"text":[{"text":"Cron runs the script as a different system user who has no permission to read another user’s environment variables, so the script must be given "},{"text":"sudo","code":true},{"text":" or run as root."}],"correct":false,"tempting":[{"text":"Cron typically runs as the same user; the issue is which shell files are read, not permissions, and "},{"text":"sudo","code":true},{"text":" would widen access for no reason."}]},{"text":[{"text":"Cron scripts cannot make network calls, so the API client fails at import and reports a missing key."}],"correct":false,"tempting":[{"text":"Cron places no restriction on networking; the error names the environment variable and is raised before any call."}]},{"text":[{"text":"Cron starts jobs with a minimal environment that never reads the shell profile, so the job must load its own configuration or the crontab must set it."}],"correct":true,"tempting":null},{"text":[{"text":"The key was set with "},{"text":"export","code":true},{"text":" in the terminal, which is case-sensitive, and cron lowercases environment variable names."}],"correct":false,"tempting":[{"text":"Cron does not alter variable names; the variable is simply not present in the environment cron provides."}]}],"order":[1,0,2,3],"why":null},"prev":{"slug":"an-endpoint-with-fastapi","title":"An HTTP endpoint with FastAPI: your function, callable by any program","minutes":9},"next":{"slug":"github-actions-ci","title":"GitHub Actions: the tests run on a machine that is not yours, before anything ships","minutes":9}}}