load-shedding 0.13.0

A python library for getting Load Shedding schedules from Eskom.

load-shedding

A Python library for retrieving load-shedding schedules and status for South Africa.

Supported Providers

• Eskom
• City of Cape Town (CoCT)
• SePush (requires API token)

Installation

pip install load-shedding

Basic Usage

1. Import the library

from load_shedding import Provider, get_stage, get_areas, get_area_schedule, Stage

2. Instantiate a Provider

Eskom or City of Cape Town

provider = Provider.ESKOM()
# OR
provider = Provider.COCT()

SePush (Requires an API token)

Sign up for EskomSePush API token first.

token = "<your secret token>"
provider = Provider.SE_PUSH(token=token)

3. Check Current Load-Shedding Stage

# Get current stage (returns a Stage enum)
stage = get_stage(provider)
print(f"Current Stage: {stage}")

4. Search for an Area

To get a schedule, you first need to find the correct Area object.

search_results = get_areas(provider, search_text="Milnerton")
for area in search_results:
    print(f"Found: {area.name} (ID: {area.id})")

area = search_results[0]

5. Get Load-Shedding Schedule

Once you have an Area, you can retrieve the schedule.

Eskom and City of Cape Town

These providers use the Area object returned from get_areas.

schedule = get_area_schedule(provider, area=area, stage=Stage.STAGE_2)

SePush (Special Handling)

For SePush, you can provide either an Area object, or a ESP Area ID or an ESP Schedule ID as a string.

NOTE: Default usage (providing an Area object) will result in more API calls than just providing an ESP Schedule ID.

# Option A: Use an Area ID (under_score format)
# This will:
# 1. Make an API call to resolve the Area's metadata.
# 2. Identify all "auto_enabled" schedules (e.g. Load Shedding + Load Reduction).
# 3. Make a subsequent API call for EACH of those schedules and merge the results.
area = "za_gt_tsh_mabopanea_5sl0"

# Option B: Use a specific Schedule ID (hyphen-format)
# This is more efficient as it fetches the schedule directly in one API call.
area = "eskomgautenglr-c"

schedule = get_area_schedule(provider, area=area, stage=Stage.STAGE_2)

Iterating the Schedule

The schedule returns a list of (start, end) tuples.

for start, end in schedule:
    print(f"From: {start} To: {end}")

Advanced Usage

Get Stage Forecast

Available for some providers (like SePush via City Power):

forecast = provider.get_stage_forecast()
for entry in forecast:
    print(f"Stage {entry['stage']} starts at {entry['start_time']}")

Development

Running Tests

Ensure you have the project dependencies installed in your virtual environment.

source venv/bin/activate

# Run all tests
python3 -m unittest discover tests

# Run specific tests
python3 -m unittest -v tests/libs/test_sepush.py tests/providers/test_sepush.py