Add rate limit information and proactive rate limit handling

[JonoPrest]

Summary

This PR adds comprehensive rate limit support to the Hypersync Python client, enabling users to access rate limit information from server responses and proactively manage rate limiting.

Key Changes

• New RateLimitInfo class: Exposes rate limit details including limit, remaining quota, reset time, cost per request, retry-after header, and suggested wait time
• New client methods:
  • get_with_rate_limit(): Returns both query response and rate limit info as a tuple
  • rate_limit_info(): Retrieves the most recently observed rate limit information
  • wait_for_rate_limit(): Async method to wait until the rate limit window resets
• New ClientConfig option: proactive_rate_limit_sleep flag to enable proactive sleeping when rate limit is exhausted (default: True)
• Updated dependencies: Bumped hypersync-client from 1.0.2 to 1.1.0 to support new rate limit APIs
• Version bump: Updated package version from 0.10.0 to 0.11.0

Implementation Details

• RateLimitInfo is a Rust struct with Python bindings that converts from the underlying hypersync_client::RateLimitInfo type
• The conversion includes computed fields like is_rate_limited() and suggested_wait_secs() from the client library
• All new async methods follow the existing pattern of using future_into_py for Python async compatibility
• The new config option is properly serialized with skip_serializing_if to maintain backward compatibility

https://claude.ai/code/session_012mwJv9YsuFKTvrgftATDB7

Summary by CodeRabbit

• New Features

  • Added rate limit management API with methods to retrieve rate limit info, fetch data with rate limit details, and wait for rate limit reset.
  • Added proactive_rate_limit_sleep configuration option to control rate limit behavior.

• Chores

  • Updated version to 0.11.0 and bumped hypersync-client dependency to 1.1.0.

[coderabbitai]

Warning

Rate limit exceeded

@JonoPrest has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 16 minutes and 11 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 25ff90d2-008d-4e58-96e8-61acb76276a2

📥 Commits

Reviewing files that changed from the base of the PR and between 58125c2 and d9204d9.

📒 Files selected for processing (1)

• Cargo.toml

📝 Walkthrough

Walkthrough

This pull request introduces rate-limiting support by adding a RateLimitInfo data type to expose server rate-limit metadata, extending ClientConfig with a proactive_rate_limit_sleep toggle, and providing new HypersyncClient methods to retrieve and await rate-limit status. The crate version is bumped to 0.11.0 with updated dependencies.

Changes

Cohort / File(s)	Summary
Version and Dependencies Cargo.toml	Bumped crate version from 0.10.0 to 0.11.0; updated hypersync-client dependency from 1.0.2 to 1.1.0.
Rate-Limit Data Modeling src/types.rs, src/config.rs	Added new RateLimitInfo struct with fields for quota, remaining, reset time, cost, retry-after, and rate-limit status flags. Introduced From conversion from hypersync_client::RateLimitInfo. Added optional proactive_rate_limit_sleep config field.
Python API Exposure hypersync/__init__.py, src/lib.rs	Exported RateLimitInfo class and extended HypersyncClient with get_with_rate_limit(), rate_limit_info(), and wait_for_rate_limit() methods. Added proactive_rate_limit_sleep option to ClientConfig.

Sequence Diagram(s)

sequenceDiagram
    participant Client as Python Client
    participant HC as HypersyncClient
    participant Inner as _HypersyncClient (Rust)
    participant Server as Hypersync Server

    Client->>HC: get_with_rate_limit(query)
    activate HC
    HC->>Inner: execute query
    activate Inner
    Inner->>Server: fetch data
    Server-->>Inner: response + rate-limit headers
    Inner-->>HC: QueryResponse + RateLimitInfo
    deactivate Inner
    HC->>HC: convert to Python types
    HC-->>Client: (QueryResponse, RateLimitInfo)
    deactivate HC

    Note over Client,Server: Proactive rate-limit handling
    Client->>HC: wait_for_rate_limit()
    activate HC
    HC->>Inner: wait until rate-limit resets
    activate Inner
    Inner-->>Inner: sleep until reset_secs elapsed
    Inner-->>HC: completed
    deactivate Inner
    HC-->>Client: resumed
    deactivate HC

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Poem

🐰 Hop with rate-limit grace!
New info flows with gentle pace,
Wait and sleep, then onward bound,
Throttling wisdom, safe and sound! 🚀

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding rate limit information and proactive rate limit handling, which is the core objective across all modified files.
Docstring Coverage	✅ Passed	Docstring coverage is 91.67% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/upgrade-hypersync-rate-limiting-IHWT1

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}