atomicds.timeseries.polling

Functions

aiter_poll(client, data_id, *[, interval, ...])	Asynchronously yield time series results without blocking the loop.
iter_poll(client, data_id, *[, interval, ...])	Yield time series results at a fixed cadence.
start_polling_task(client, data_id, *[, ...])	Start the async poller as an asyncio.Task and stream results to a callback.
start_polling_thread(client, data_id, *[, ...])	Start the sync poller in a background thread and stream results to a callback.

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]

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).

async atomicds.timeseries.polling.aiter_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) → AsyncIterator[DataFrame]

Asynchronously yield time series results without blocking the loop.

Uses the the same semantics as iter_poll.

Parameters:

• client – API client instance forwarded to the provider.

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

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

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

• 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:

AsyncIterator[DataFrame]

Notes

• Uses asyncio.to_thread so provider calls never block the event loop.

• Drift-corrected scheduling preserves cadence even with slow polls.

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

atomicds.timeseries.polling.start_polling_thread(client, data_id: str, *, interval: float = 1.0, last_n: int | None = None, on_result: Callable[[DataFrame], None], **kwargs) → Event

Start the sync poller in a background thread and stream results to a callback.

Wraps iter_poll in a daemon thread and invokes on_result(result) for each yielded item. Returns a threading.Event that can be set to stop polling gracefully.

Parameters:

• client – API client instance forwarded to the provider.

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

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

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

• on_result (Callable[[DataFrame], None]) – Callback invoked with each yielded result.

• **kwargs – Additional keyword arguments forwarded to iter_poll (e.g., distinct_by, until, max_polls, fire_immediately, jitter, on_error).

Returns:

Event that, when set, requests the polling thread to stop.

Return type:

threading.Event

atomicds.timeseries.polling.start_polling_task(client, data_id: str, *, interval: float = 1.0, last_n: int | None = None, on_result: Callable[[DataFrame], Any] | None = None, **kwargs) → Task[None]

Start the async poller as an asyncio.Task and stream results to a callback.

Wraps aiter_poll in a background Task. If on_result returns a coroutine, it will be awaited before the next iteration.

Parameters:

• client – API client instance forwarded to the provider.

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

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

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

• on_result (Callable[[DataFrame], Any] | None) – Optional callback invoked with each yielded result. If it returns a coroutine, it will be awaited.

• **kwargs – Additional keyword arguments forwarded to aiter_poll (e.g., distinct_by, until, max_polls, fire_immediately, jitter, on_error).

Returns:

A created and started Task. Cancel it to stop polling.

Return type:

asyncio.Task[None]

Raises:

RuntimeError – If no running event loop is available when called.