euphraxiia/loadsheddding-notifier

A practical load shedding schedule tracker for South African suburbs. Fetches Eskom outage schedules and provides notification capabilities. Built with Flask, implements RESTful API integration, and includes comprehensive test coverage. # Load Shedding Notifier A Flask web application for tracking load shedding schedules in South Africa. Subscribe to email notifications and never be caught off guard by Eskom again. ## Features - **Schedule Lookup** - Search by suburb name or area code to view upcoming load shedding times. - **Email Notifications** - Receive alerts 2 hours before a scheduled outage so you can prepare. - **Subscription Management** - Subscribe, update your area, or toggle notifications on and off. - **Area Search** - Find your EskomSePush area code by searching for your suburb. - **Mock Data** - Develop and test without an API key using built-in mock schedules. - **Caching** - Results are cached to avoid hammering the EskomSePush API. - **SQLite Storage** - User preferences and schedules are persisted in a lightweight database. ## Technology Stack - **Python 3.10+** - **Flask** - Web framework - **Flask-SQLAlchemy / SQLAlchemy** - ORM and database management - **SQLite** - Database - **Requests** - HTTP client for the EskomSePush API - **smtplib** - Email delivery - **pytest** - Testing framework ## Installation ```bash # Clone the repository git clone github.com cd loadshedding-notifier # Create a virtual environment python3 -m venv venv source venv/bin/activate # Install dependencies pip install -r requirements.txt ``` ## Configuration 1. Copy the example environment file: ```bash cp env.example .env ``` 2. Edit `.env` and fill in your settings: | Variable | Description | Default | |---|---|---| | `ESP_API_KEY` | Your EskomSePush API key (free at sepush.co.za) | _(empty - uses mock data)_ | | `USE_MOCK_DATA` | Set to `false` when you have a real API key | `true` | | `SMTP_USERNAME` | Gmail address (or other SMTP provider) | _(empty)_ | | `SMTP_PASSWORD` | App password for your email account | _(empty)_ | | `SECRET_KEY` | A random secret for Flask sessions | `dev-secret-key...` | For Gmail SMTP, you will need to …