ThrottledHypersyncClient

Documentation for eth_defi.hypersync.session.ThrottledHypersyncClient Python class.

class ThrottledHypersyncClient

Bases: object

Drop-in wrapper for hypersync.HypersyncClient with built-in rate limiting and stream tuning.

Throttles one-shot API calls (stream, get_chain_id, get_height) through a shared pyrate_limiter.Limiter with an SQLite-backed token bucket.

Stream tuning parameters (concurrency, batch sizes, response byte limits) are stored on the client and used to build a hypersync.StreamConfig automatically when stream() is called without an explicit config.

recv() is intentionally not throttled — adding a Python-side delay on recv() only slows down buffer reads without reducing actual API load. Internal Rust retries are disabled (max_num_retries=0) so 429 errors surface immediately to the Python-side retry logic.

For stream tuning parameter documentation see Envio HyperSync StreamConfig tuning.

Note

This class intentionally does not subclass hypersync.HypersyncClient (a Rust-backed PyO3 class). It relies on duck typing — callers that accept HypersyncClient should also accept this wrapper. Use is_hypersync_client() for isinstance-style checks that accept both types.

Parameters

client – The underlying native hypersync.HypersyncClient.
limiter – Shared pyrate_limiter.Limiter for rate limiting.
concurrency – Number of requests in flight — the main throughput knob. None uses the Hypersync server default (10).
batch_size – Initial block range for the first wave of requests, before density has been measured. None uses the server default (1000).
min_batch_size – Lower limit on projected block count per request. None uses the server default.
max_batch_size – Hard cap on blocks per request. None means no cap.
response_bytes_ceiling – Upper target for response size in bytes (macOS wheel). None uses the server default.
response_bytes_floor – Lower target for response size in bytes (macOS wheel). None uses the server default.
response_bytes_target – Target response size in bytes (Linux wheel). None uses the server default.

Note

The hypersync 1.1.0 Rust wheel exposes different response-byte parameter names on different platforms. Pass whichever your platform supports; unsupported names are silently ignored.

Methods summary

`__init__`(client, limiter, *[, concurrency, ...])
`create_stream_config`(**overrides)	Build a `hypersync.StreamConfig` from stored tuning params.
`get_chain_id`()	Get chain ID, throttled.
`get_height`()	Get latest block height, throttled.
`stream`(query[, config])	Open a stream, throttled at the setup level.

__init__(client, limiter, *, concurrency=None, batch_size=None, min_batch_size=None, max_batch_size=None, response_bytes_ceiling=None, response_bytes_floor=None, response_bytes_target=None, max_buffered_bytes=None)

Parameters

client (hypersync.HypersyncClient) –
limiter (pyrate_limiter.limiter.Limiter) –
concurrency (Optional[int]) –
batch_size (Optional[int]) –
min_batch_size (Optional[int]) –
max_batch_size (Optional[int]) –
response_bytes_ceiling (Optional[int]) –
response_bytes_floor (Optional[int]) –
response_bytes_target (Optional[int]) –
max_buffered_bytes (Optional[int]) –

create_stream_config(**overrides)

Build a hypersync.StreamConfig from stored tuning params.

Any keyword arguments override the stored values for this single call. Only non-None values are passed to the constructor.

Example:

# Use all stored defaults
config = client.create_stream_config()

# Override concurrency for one call
config = client.create_stream_config(concurrency=30)

Return type: hypersync.StreamConfig

async get_chain_id(): Get chain ID, throttled.

async get_height(): Get latest block height, throttled.

async stream(query, config=None)

Open a stream, throttled at the setup level.

When config is None, a hypersync.StreamConfig is built automatically from the stored tuning parameters via create_stream_config(). Pass an explicit config to override completely.

Parameters: config (Optional[hypersync.StreamConfig]) –
Return type: hypersync.QueryResponseStream