BandwidthGuard

Sliding-window bandwidth guard for throttling HTTP API calls.

class scamander.api.bandwidth_guard.BandwidthGuard(limit_mb: float, window_secs: float = 300.0, threshold: float = 0.9)

Bases: object

Sliding-window bandwidth guard for HTTP API calls.

Accumulates response body sizes within a rolling window_secs window. When cumulative usage reaches threshold fraction of limit_mb, record() sleeps until the oldest entry exits the window, preventing hard gateway rejections.

Parameters:

  • limit_mb – Bandwidth cap in megabytes per window.

  • window_secs – Window length in seconds. Defaults to 300.

  • threshold – Fraction of limit_mb at which throttling activates. Must be between 0 and 1. Defaults to 0.9 (90 %).

Example:

guard = BandwidthGuard(limit_mb=350, window_secs=300, threshold=0.9)
response = session.get(url)
guard.record(len(response.content))
record(response_bytes: int)

Record a response size and pause when the bandwidth threshold is reached.

Parameters:

response_bytes – Size of the response body just received, in bytes.