Add max_rate_limit_wait to GithubRetry to cap rate limit backoff

[tanistheta]

Problem

GithubRetry currently waits until X-RateLimit-Reset (primary rate limit) or
secondary_rate_wait (secondary rate limit) before retrying, with no way to cap
that wait. If GitHub reports a reset far in the future, callers with hard
timeouts (e.g. Celery tasks) end up blocked well past their own deadline.

Approach

Adds an optional max_rate_limit_wait parameter to GithubRetry.__init__.
When the computed backoff for either a primary or secondary rate limit error
would exceed this cap, GithubRetry.increment() raises a new
RateLimitExceededExceedsMaxWait exception (subclass of
RateLimitExceededException) instead of waiting. The exception exposes
.wait (the backoff that would have been required) and the usual
.status / .data / .headers from GithubException, so callers can
inspect the raw rate-limit response and decide how to handle it themselves.

Defaults to None (no cap), so existing behavior is unchanged unless a
caller opts in.

Tests

Added three tests in tests/GithubRetry.py:

• test_primary_rate_error_exceeds_max_wait — primary rate limit backoff
  exceeding the cap raises with the correct .wait/.status/.data
• test_primary_rate_error_within_max_wait — backoff under the cap still
  retries normally
• test_secondary_rate_error_exceeds_max_wait — same cap behavior on the
  secondary rate limit path

Fixes #3473

[EnricoMi]

Thanks for raising this, I think this is very useful given retry-after headers can be an hour in the future. Minor documentation comment.

[EnricoMi]

Should be explicit here that if max_rate_limit_wait < secondary_rate_wait, any secondary rate limit error will raise an exception and never wait.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.01%. Comparing base (7de2644) to head (df2fcd6).
⚠️ Report is 56 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3540      +/-   ##
==========================================
+ Coverage   97.00%   97.01%   +0.01%     
==========================================
  Files         172      176       +4     
  Lines       18934    19915     +981     
==========================================
+ Hits        18366    19321     +955     
- Misses        568      594      +26     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

Test Results

     9 files  ± 0       9 suites  ±0   5m 54s ⏱️ +3s
 1 151 tests + 3   1 151 ✅ + 3  0 💤 ±0  0 ❌ ±0 
14 225 runs  +24  14 224 ✅ +24  1 💤 ±0  0 ❌ ±0 

Results for commit df2fcd6. ± Comparison against base commit 6754682.

♻️ This comment has been updated with latest results.

[EnricoMi]

LGTM!

[djsigmann]

Thanks for merging this :), when might we see a new release with these changes?