synology_apm_repo.sdk.presentation.progress module

Progress/ProgressMeter: the progress contract every frontend builds on, so rate/ETA math is computed once.

  1. total is the planned work the caller passes in (a sparse image’s planned chunks, not its logical size).

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

  3. Rate samples are taken at most every rate_sample_interval, however often ProgressMeter.update is called, which bounds the sample deque.

  4. ProgressMeter.update is cheap to call per chunk; it forwards to the wrapped callback only every min_interval seconds or min_delta units, 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.

  5. 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: object

One snapshot of a long-running operation’s state.

Variables:
  • phase (Literal['discovering', 'reading', 'verifying']) – What the operation is doing.

  • determinate (bool) – Whether total is meaningful.

  • done (int) – How many units are finished.

  • total (int | None) – None when the total is unknown.

  • unit (Literal['bytes', 'items', 'buckets']) – What done/total count.

  • detail (str) – The file/object currently being processed, for UI display.

  • found (int | None) – Incremental result count when total is unknown.

phase: Literal['discovering', 'reading', 'verifying']
determinate: bool
done: int
total: int | None
unit: Literal['bytes', 'items', 'buckets']
detail: str
found: int | None
type synology_apm_repo.sdk.presentation.progress.ProgressCallback = Callable[[Progress], Awaitable[None]]

Receives each Progress snapshot of a long-running operation.

class synology_apm_repo.sdk.presentation.progress.FormattedProgress(rate, eta, elapsed)

Bases: object

A ProgressMeter’s rate, ETA and elapsed time as display text.

Variables:
  • rate (str) – "" until a rate has been measured.

  • eta (str) – "" while unknown (no total, or still warming up).

  • elapsed (str) – Always set.

rate: str
eta: str
elapsed: str
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: object

Smooths raw Progress snapshots into a stable rate/ETA (rules 2-3) and rate-limits how often the wrapped callback actually fires (rule 4). Construct one per operation; call update as often as convenient (every chunk is fine).

Parameters:
  • callback (ProgressCallback | None) – Awaited with a Progress when the throttle fires; None still tracks rate/ETA without notifying.

  • min_interval (float) – Minimum seconds between callback invocations.

  • min_delta (int) – Also notify once done has advanced this much since the last notification; 0 disables 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_fraction of 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 progress and, 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.

property latest: Progress | None

The most recent snapshot passed to update, notified or not.

property rate: float

The smoothed rate, in units per second.

property elapsed: timedelta

Time since the first update; zero before it.

formatted(unit)

The current rate (per unit), ETA and elapsed time as text.

property eta: timedelta | None

None when the total is unknown, no progress has been recorded yet, or too little time/fraction has elapsed to trust a rate estimate (rule 2’s warm-up window).

synology_apm_repo.sdk.presentation.progress.reading_progress_callback(meter)

Adapts meter to the raw (done, total) shape of an export’s progress callback (run_export), as a phase="reading" byte count.