Automation Guide

How to customise, schedule, and extend the scripts in this collection.

Quick Start

bash

# Install dependencies
pip install pyyaml requests jinja2

# Run any script directly
python scripts/file_organizer.py --source ~/Downloads --dest ~/Sorted

# Or use the runner for logging & timing
python -m utils.runner scripts/file_organizer.py --source ~/Downloads --dest ~/Sorted

Configuration

All scripts read from configs/scripts_config.yaml. Edit the file to

set defaults so you don't need to pass CLI flags every time:

yaml

scripts:
 file_organizer:
  source: "~/Downloads"
  dest: "~/Sorted"
  strategy: "extension"

Scheduling with Cron

Add entries to your crontab (crontab -e) to run scripts automatically:

cron

# Organise downloads every day at 8 AM
0 8 * * * cd /path/to/scripts && python scripts/file_organizer.py --source ~/Downloads --dest ~/Sorted

# Back up the database nightly at 2 AM, keep 7 copies
0 2 * * * cd /path/to/scripts && python scripts/db_backup.py --db /data/app.db --dest /backups --keep 7

# Check SSL certs every Monday at 9 AM
0 9 * * 1 cd /path/to/scripts && python scripts/ssl_checker.py example.com api.example.com

# Clean Docker every Sunday at midnight
0 0 * * 0 cd /path/to/scripts && python scripts/docker_cleanup.py --include-volumes

# Analyse logs every 6 hours
0 */6 * * * cd /path/to/scripts && python scripts/log_analyzer.py --log-dir /var/log/app

Systemd Timers (Alternative to Cron)

For Linux systems using systemd:

ini

# /etc/systemd/system/db-backup.timer
[Unit]
Description=Database backup timer

[Timer]
OnCalendar=*-*-* 02:00:00
Persistent=true

[Install]
WantedBy=timers.target

Adding Notifications

The utils/notifier.py module supports Slack, email, and generic webhooks.

1. Fill in your credentials in configs/scripts_config.yaml.

2. Use the notifier in your scripts:

python

from utils.notifier import Notifier

notifier = Notifier.from_config("configs/scripts_config.yaml")
notifier.send("Daily backup completed successfully", channel="slack")

Writing Your Own Scripts

Follow this pattern to integrate with the runner and notifier:

python

"""my_script.py — one-line description."""

from __future__ import annotations
import argparse

def main() -> None:
  parser = argparse.ArgumentParser(description="My automation script")
  parser.add_argument("--input", required=True)
  args = parser.parse_args()

  # Your logic here
  print(f"Processing {args.input}")

if __name__ == "__main__":
  main()

Key conventions:

Always define a main() function (the runner calls it)
Use argparse for CLI arguments
Use from __future__ import annotations for modern type hints
Return a non-zero exit code on failure

Script Reference

Script	Key flags
`file_organizer`	`--source`, `--dest`, `--by`, `--dry-run`
`csv_processor`	`--output`, `--drop-empty`, `--dedupe`, `--filter`, `--columns`
`api_tester`	`--config`, `--url`, `--method`, `--expect`
`log_analyzer`	`--log-dir`, `--file`, `--pattern`, `--top`
`db_backup`	`--db`, `--pg-url`, `--dest`, `--keep`
`env_checker`	`--min-python`, `--requirements`, `--packages`, `--env-vars`
`report_generator`	`--data`, `--template`, `--output`, `--format`
`git_stats`	`--repo`, `--since`, `--top`
`docker_cleanup`	`--dry-run`, `--include-volumes`
`ssl_checker`	`domains...`, `--domains-file`, `--warn-days`

Testing