# battery-guard
*A Python library to pause work until the battery is charged enough to continue*

Designed for power-hungry laptops connected to slow chargers.

Use it as a decorator on your methods. In the example below, each call to `process` first checks the battery.
If it is below 25%, execution is paused until it is back at or above that same 25%.

```python
from battery_guard import battery_guard

@battery_guard(minimum=25)
def process(item):
    ...  # a power hungry task probably

for item in items:
    process(item)
```

The battery is only checked when the decorated function is called, a call that is already running is never paused.
It therefore works best on a function that is called repeatedly, like the body of a loop, rather than on one long-running function.

To pause when the battery dips below 20%, and only continue once it has charged back up to 30%, pass `resume` as well:

```python
@battery_guard(minimum=20, resume=30)
```

When there is no function to decorate, for example in a notebook cell, block directly:

```python
from battery_guard import wait_for_battery

wait_for_battery(minimum=25)
```

## Logging

Messages are emitted through the standard `logging` module, under the `battery_guard` logger.
Warnings (such as failing to read the battery status) are shown by default.
To also see when execution pauses and resumes, enable `INFO` level, or `DEBUG` to see every battery check:

```python
import logging

logging.basicConfig(level=logging.INFO)
```