Publish a first version of battery_guard on PyPI

README.md

@@ -0,0 +1,47 @@
+# 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)
+```