Feat/configurable timeout

[geoffhancock]

Expose request timeout and historical chunk size, and point timeout errors at both

Why

The client hardcodes a 60 s read timeout and splits historical pulls into 30-day requests. Neither is configurable. When the API is slow to answer a large span, a user waits ~4 minutes (60 s x 4 attempts from the session's retry policy) and then gets RuntimeError: API Request Failed: ... Read timed out with no indication of why and nothing to change. The only workaround has been to monkeypatch the private _get_chunks.

This happened in August 2026: 30-day co2_moer pulls for some regions took over 180 s server-side while the same query at 10 days took ~11 s. The backend cause is being addressed separately; this PR is about not leaving SDK users stranded the next time something similar happens. This PR adds knobs; a follow-on PR will propose a more graceful retry strategy.

What changes

1. timeout on the constructor (WattTimeBase.__init__, default (10, 60)), applied at all three HTTP call sites. Accepts the standard requests forms: a number, a (connect, read) tuple, or None.
2. chunk_size on get_historical_jsons / _pandas / _csv (default None = 30 days, unchanged). _get_chunks now accepts None and rejects sizes of 5 minutes or less.
3. Timeout errors carry a hint naming both knobs. Once retries are exhausted, requests raises ConnectionError -> MaxRetryError -> ReadTimeoutError rather than ReadTimeout, so a small _is_timeout helper walks the exception chain.

Both new parameters are keyword-only, and the internal call chain (get_historical_csv -> _pandas -> _jsons) passes every defaulted argument by keyword -- the same convention as the include_imputed_marker misrouting fix, so argument-order differences between signatures cannot silently route a value to the wrong parameter.

Implications

• The default connect timeout on the data path drops from 60 s to 10 s. That request used a scalar 60 (connect = read = 60); it now shares the (10, 60) default with login and register. The default read timeout of 60 s is unchanged at all three sites.
• _get_chunks raises ValueError for chunk_size <= 5 min. Before, zero or negative never terminated and 5 minutes produced an inverted chunk. No caller passed such values.
• Timeouts are per attempt. The session retries up to 3 times with backoff, so a failing request takes roughly 4 x read_timeout + 6 s to surface. Documented on the parameter.
• Nothing changes by default. Default chunking, default timeouts for login/register, and response shapes are as before. Both new parameters are keyword-only, so existing positional callers are unaffected and the positional contract of every signature is frozen where it is today.
• Smaller chunk_size means more requests and, with include_meta=True, more meta rows -- one per response, as today.
• The README note for timeout / chunk_size is the final commit on its own; drop it if you would rather not have that section.

Stacked on #75: the first commit here is #75's and drops out once it merges. Both PRs touch the _csv -> _pandas -> _jsons call chain, so this ordering avoids a conflict.

Tests

Nine mocked tests, no network: the timeout reaches all three call sites; tuple/scalar/None accepted; the new parameters are keyword-only and existing positional calls still work; the hint appears for both the bare and the retry-wrapped timeout (with __cause__ preserved) and not for other errors; chunk_size is honoured by the chunker, forwarded from _pandas, and controls the request count; the validation floor.

Follow-up (separate PR #77 )

These knobs let a user react, but they still have to hit the error first. PR #77 proposes a design concept to make retry policy failure-class-aware so the common cases need no intervention: split the span and retry smaller on read timeout / 504 instead of re-issuing the identical request four times; keep backoff for 5xx; refresh the token on 401; fail fast on other 4xx. It builds on the chunk_size plumbing here, which is why this lands first.

🤖 Generated with the help of Claude Code