synology_apm_repo.sdk.presentation.progress module¶
Progress/ProgressMeter: the progress contract every frontend
builds on, so rate/ETA math is computed once.
totalis the planned work the caller passes in (a sparse image’s planned chunks, not its logical size).Rate is a windowed average over the last
rate_window_seconds. ETA stays unknown through a warm-up window and is quantized so it doesn’t jitter.Rate samples are taken at most every
rate_sample_interval, however oftenProgressMeter.updateis called, which bounds the sample deque.ProgressMeter.updateis cheap to call per chunk; it forwards to the wrapped callback only everymin_intervalseconds ormin_deltaunits, whichever comes first – except that the snapshot completing a known total and the first snapshot of a new phase always notify, so a display never stops short of 100% or misses a phase.A new phase (or unit) restarts the rate window; a count that goes back within one never makes the rate negative.
- class synology_apm_repo.sdk.presentation.progress.Progress(phase, determinate, done=0, total=None, unit='bytes', detail='', found=None)¶
Bases:
objectOne snapshot of a long-running operation’s state.
- Variables:
phase (Literal['discovering', 'reading', 'verifying']) – What the operation is doing.
determinate (bool) – Whether
totalis meaningful.done (int) – How many
units are finished.total (int | None) –
Nonewhen the total is unknown.unit (Literal['bytes', 'items', 'buckets']) – What
done/totalcount.detail (str) – The file/object currently being processed, for UI display.
found (int | None) – Incremental result count when
totalis unknown.
- type synology_apm_repo.sdk.presentation.progress.ProgressCallback = Callable[[Progress], Awaitable[None]]¶
Receives each
Progresssnapshot of a long-running operation.
- class synology_apm_repo.sdk.presentation.progress.FormattedProgress(rate, eta, elapsed)¶
Bases:
objectA
ProgressMeter’s rate, ETA and elapsed time as display text.- Variables:
- class synology_apm_repo.sdk.presentation.progress.ProgressMeter(callback=None, *, min_interval=0.1, min_delta=0, rate_window_seconds=3.0, rate_sample_interval=0.2, eta_warmup_seconds=2.0, eta_warmup_fraction=0.01, now=<built-in function monotonic>)¶
Bases:
objectSmooths raw
Progresssnapshots into a stable rate/ETA (rules 2-3) and rate-limits how often the wrapped callback actually fires (rule 4). Construct one per operation; callupdateas often as convenient (every chunk is fine).- Parameters:
callback (ProgressCallback | None) – Awaited with a
Progresswhen the throttle fires;Nonestill tracks rate/ETA without notifying.min_interval (float) – Minimum seconds between callback invocations.
min_delta (int) – Also notify once
donehas advanced this much since the last notification;0disables the delta trigger.rate_window_seconds (float) – Span of the windowed rate average.
rate_sample_interval (float) – Minimum seconds between rate samples.
eta_warmup_seconds (float) – ETA stays unknown until this much time has elapsed or
eta_warmup_fractionof the total is done.eta_warmup_fraction (float) – See
eta_warmup_seconds.now (Callable[[], float]) – Monotonic clock in seconds; injectable for tests.
- async update(progress)¶
Record
progressand, if rule 4’s throttle says so, notify.Awaits the callback inline, so a slow UI callback back-pressures the producer rather than piling up tasks; it is awaited only when the throttle fires.
- formatted(unit)¶
The current rate (per
unit), ETA and elapsed time as text.
- synology_apm_repo.sdk.presentation.progress.reading_progress_callback(meter)¶
Adapts
meterto the raw(done, total)shape of an export’sprogresscallback (run_export), as aphase="reading"byte count.