load-shedding 0.14.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']}")

SePush API v2 → v3 Migration

SePush migrated their API from v2 to v3. Area IDs changed format:

Version	Format	Example
v2 (old)	hyphens	eskde-10-fourways
v3 (current)	underscores	za_gt_jhb_fourways_4pef

SePush.area() will raise SePushError immediately (without making any HTTP request) if the supplied ID contains a hyphen. This is a fast-fail guard to prevent quota burn from repeated failed requests. Schedule IDs (used with SePush.schedule()) continue to use hyphens and are not affected by this check.

If you stored area IDs before the v3 migration, call areas_search() again to obtain the correct v3 IDs.

User-Agent

Every request sends a User-Agent header:

load_shedding/0.14.0

Callers can append optional context so that requests are attributable:

from load_shedding.libs.sepush import SePush

sp = SePush(
    token="<your-token>",
    user_agent_context={
        "my_app": "1.0.0",
        "python": "3.13",
    },
)
# Sends: User-Agent: load_shedding/0.14.0 (my_app/1.0.0; python/3.13)

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