api_24sea.datasignals.progress
==============================

.. py:module:: api_24sea.datasignals.progress

.. autoapi-nested-parse::

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

.. autoapisummary::

   api_24sea.datasignals.progress.QueryProgress


Functions
---------

.. autoapisummary::

   api_24sea.datasignals.progress.request_timing_features
   api_24sea.datasignals.progress.estimate_request_seconds
   api_24sea.datasignals.progress.estimated_fraction
   api_24sea.datasignals.progress.scheduled_seconds


Module Contents
---------------

.. py:function:: request_timing_features(request: api_24sea.datasignals.planning.DataRequest) -> Tuple[float, float, float, float, float]

   Describe request overhead, locations and metric-day work.

   Parameters
   ----------
   request : DataRequest
       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.


.. py:function:: estimate_request_seconds(request: api_24sea.datasignals.planning.DataRequest) -> float

   Estimate uncached Parquet retrieval and decoding time in seconds.

   Parameters
   ----------
   request : DataRequest
       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.


.. py:function:: 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


.. py:function:: 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


.. py:class:: QueryProgress(plan: api_24sea.datasignals.planning.DataRequestPlan, concurrency: Optional[int] = None)

   Keep one estimated percentage bar alive until result assembly ends.

   Parameters
   ----------
   plan : DataRequestPlan
       Ordered HTTP requests with their metric metadata.
   concurrency : int, 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.


   .. py:method:: request_started(index: int) -> None

      Start timing only after this request acquires an execution slot.



   .. py:method:: request_finished(index: int) -> None

      Record successful retrieval and decoding, including cache hits.



   .. py:method:: tick() -> None

      Refresh during blocking HTTP waits without scheduling extra work.



   .. py:method:: refresh() -> None

      Reconcile elapsed estimates and observed completions monotonically.