Metadata-Version: 2.4
Name: load-shedding
Version: 0.14.0
Summary: A python library for getting Load Shedding schedules from Eskom.
Home-page: https://gitlab.com/wernerhp/load-shedding
Author: Werner Pieterson
Author-email: wernerhp@gmail.com
Project-URL: Bug Tracker, https://gitlab.com/wernerhp/load-shedding/issues
Keywords: eskom,load shedding,south africa,api
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: beautifulsoup4~=4.9.3
Requires-Dist: certifi~=2021.10.8
Requires-Dist: urllib3[secure]>=1.26.7
Dynamic: license-file

# 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

```bash
pip install load-shedding
```

## Basic Usage

### 1. Import the library

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

### 2. Instantiate a Provider

#### Eskom or City of Cape Town
```python
provider = Provider.ESKOM()
# OR
provider = Provider.COCT()
```

#### SePush (Requires an API token)
Sign up for [EskomSePush API](https://eskomsepush.gumroad.com/l/api) token first.
```python
token = "<your secret token>"
provider = Provider.SE_PUSH(token=token)
```

### 3. Check Current Load-Shedding Stage

```python
# 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.

```python
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`.

```python
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.

```python
# 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.

```python
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):

```python
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:

```python
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.

```bash
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
```

