api_24sea.datasignals.progress#

Estimated query progress shared by blocking and asynchronous clients.

The timing model uses the requested time span, location count and metric families. See docs/explanation/query-progress.md for its equations and limitations. This is an elapsed-time estimate, not server-side progress telemetry.

Classes#

QueryProgress

Keep one estimated percentage bar alive until result assembly ends.

Functions#

`request_timing_features`(→ Tuple[float, float, float, ...)	Describe request overhead, locations and metric-day work.
`estimate_request_seconds`(→ float)	Estimate uncached Parquet retrieval and decoding time in seconds.
`estimated_fraction`(→ float)	Advance to 90% at the estimate, then approach 99% on an overrun.
`scheduled_seconds`(→ float)	Estimate wall time for ordered jobs assigned to available slots.

Module Contents#

request_timing_features(request: api_24sea.datasignals.planning.DataRequest) → Tuple[float, float, float, float, float]#

Describe request overhead, locations and metric-day work.

Parameters#

requestDataRequest: Planned request with selected metric metadata and UTC bounds.

Returns#

tuple of float: Intercept, extra locations, scalar metric-days times log1p(days / 30), cycle-count metric-days and MPE metric-days. Counts include requested metrics even when their data is sparse.

estimate_request_seconds(request: api_24sea.datasignals.planning.DataRequest) → float#

Estimate uncached Parquet retrieval and decoding time in seconds.

Parameters#

requestDataRequest: One planned request. Other sites and unmeasured metric families use the same model; their estimates have not been calibrated separately.

Returns#

float: Positive duration estimate. Cache hits are allowed to finish sooner.

estimated_fraction(elapsed: float, expected: float) → float#

Advance to 90% at the estimate, then approach 99% on an overrun.

Examples#

>>> estimated_fraction(5, 10)
0.45
>>> estimated_fraction(10, 10)
0.9
>>> 0.9 < estimated_fraction(20, 10) < 0.99
True

scheduled_seconds(durations: Sequence[float], concurrency: int) → float#

Estimate wall time for ordered jobs assigned to available slots.

Examples#

>>> scheduled_seconds([10, 5, 5], 2)
10.0
>>> scheduled_seconds([], 1)
0.0

class QueryProgress(plan: api_24sea.datasignals.planning.DataRequestPlan, concurrency: int | None = None)#

Keep one estimated percentage bar alive until result assembly ends.

Parameters#

planDataRequestPlan: Ordered HTTP requests with their metric metadata.
concurrencyint, optional: Effective execution concurrency, including a blocking client’s explicit thread limit. Defaults to the plan’s concurrency.

Notes#

Request weights reflect expected duration. Only successful requests count as completed, and only a successful context exit reaches 100%. Notebook and terminal rendering use the existing SDK environment check.

request_started(index: int) → None#: Start timing only after this request acquires an execution slot.

request_finished(index: int) → None#: Record successful retrieval and decoding, including cache hits.

tick() → None#: Refresh during blocking HTTP waits without scheduling extra work.

refresh() → None#: Reconcile elapsed estimates and observed completions monotonically.