Feat/adaptive retries

README.md

@@ -74,6 +74,29 @@ wt_hist.get_historical_csv(
 )
 ```
 
+#### Tuning requests that time out
+
+Historical pulls are split into 30-day requests, each with a 60 s read timeout. If the API is slow to answer a large span, a request can time out and the error message will say so. Two options, which can be combined:
+
+```python
+from datetime import timedelta
+from watttime import WattTimeHistorical
+
+# allow each request more time: (connect, read) seconds
+wt_hist = WattTimeHistorical(username, password, timeout=(10, 300))
+
+# or make each request cover less time
+moers = wt_hist.get_historical_pandas(
+    start = '2022-01-01 00:00Z',
+    end = '2023-01-01 00:00Z',
+    region = 'CAISO_NORTH',
+    signal_type = 'co2_moer',
+    chunk_size = timedelta(days=10)
+)
+```
+
+A request that times out is not simply retried: on the historical endpoints the client splits its time span in half and asks again (up to twice), logging a warning each time, so occasional slowness is absorbed without any of the above. Connection errors and transient server errors are retried up to three times with backoff. When the client does give up it raises `WattTimeRequestError`, whose `kind` attribute (`"timeout"`, `"http_401"`, `"http_4xx"`, `"http_5xx"`, `"connection"`) lets your code decide what to do without parsing the message.
+
 You could also combine these classes to iterate through all regions where you have access to data:
 
 ```python