atomicds.timeseries.polling.iter_poll

atomicds.timeseries.polling.iter_poll(client, data_id: str, *, interval: float = 1.0, last_n: int | None = None, distinct_by: Callable[[DataFrame], Any] | None = None, until: Callable[[DataFrame], bool] | None = None, max_polls: int | None = None, fire_immediately: bool = True, jitter: float = 0.0, on_error: Callable[[BaseException], None] | None = None) → Iterator[DataFrame][source]

Yield time series results at a fixed cadence.

Supports deduplication (via a key extractor), stop conditions, bounded polling, optional jitter, and non-fatal error handling.

Parameters:

  • client – API client instance forwarded to the provider.

  • data_id (str) – Identifier to fetch data for.

  • last_n (int | None) – Last number of time series data points to poll. None is all.

  • interval (float) – Seconds between polls. Defaults to 1.0.

  • distinct_by (Callable[[DataFrame], Any] | None) – Optional function mapping a result to a hashable key for deduping. If provided, only results with a new key are yielded.

  • until (Callable[[DataFrame], bool] | None) – Optional predicate; stop when it returns True for a result.

  • max_polls (int | None) – Optional maximum number of polls before stopping.

  • fire_immediately (bool) – If True, perform the first poll immediately; otherwise wait one interval before the first poll. Defaults to True.

  • jitter (float) – Optional random delay (0..jitter) added to each sleep to avoid thundering herds. Clamped at interval. Defaults to 0.0.

  • on_error (Callable[[BaseException], None] | None) – Optional error handler called with the raised exception when a poll fails. Errors are swallowed so polling continues.

Yields:

Any – Each (optionally deduped) time series data frame result.

Return type:

Iterator[DataFrame]

Notes

  • Uses drift-corrected scheduling to maintain the requested cadence even if individual polls are slow.

  • Stops when until is satisfied or max_polls is reached (if set).