Progress + cancellation

Opt-in transfer instrumentation. Pass progress_name="<label>" to download_file(), s3_upload_file(), or s3_download_file() and the transfer registers with the shared progress_registry. From there the GUI or a JSON action can poll the reporter snapshot or cancel the transfer mid-flight.

Transfer progress + cancellation primitives.

Long-running transfers (HTTP downloads, S3 uploads/downloads, …) accept a named handle from the shared progress_registry. The registry keeps a ProgressReporter (bytes transferred, optional total) and a CancellationToken per name so the GUI or a JSON action can observe progress or cancel mid-flight.

Instrumentation is opt-in: callers pass progress_name="<label>" to enable tracking. When omitted, transfers run exactly as before with zero overhead beyond one attribute lookup.

class automation_file.core.progress.CancellationToken[source]

Bases: object

Thread-safe boolean flag, pollable from worker threads.

cancel()[source]

Return type:: None

property is_cancelled: bool

raise_if_cancelled()[source]

Return type:: None

exception automation_file.core.progress.CancelledException[source]

Bases: FileAutomationException

Raised when a cancellable operation is asked to stop mid-flight.

class automation_file.core.progress.ProgressRegistry[source]

Bases: object

Named handles so JSON actions / the GUI can address ongoing transfers.

cancel(name)[source]

Parameters:: name (str)
Return type:: bool

clear_finished()[source]

Return type:: int

create(name, total=None)[source]

Parameters:

name (str)
total (int | None)

Return type:

tuple[ProgressReporter, CancellationToken]

forget(name)[source]

Parameters:: name (str)
Return type:: bool

list()[source]

Return type:: list[dict[str, Any]]

lookup(name)[source]

Parameters:: name (str)
Return type:: tuple[ProgressReporter, CancellationToken] | None

class automation_file.core.progress.ProgressReporter(name, total=None, transferred=0, status='running', started_at=<factory>, finished_at=None, _lock=<factory>)[source]

Bases: object

Tracks bytes transferred for one named operation.

Parameters:

name (str)
total (int | None)
transferred (int)
status (str)
started_at (float)
finished_at (float | None)
_lock (allocate_lock)

finish(status='done')[source]

Parameters:: status (str)
Return type:: None

finished_at: float | None = None

property is_finished: bool

name: str

snapshot()[source]

Return type:: dict[str, Any]

started_at: float

status: str = 'running'

total: int | None = None

transferred: int = 0

update(delta)[source]

Parameters:: delta (int)
Return type:: None

automation_file.core.progress.progress_cancel(name)[source]

Cancel the named transfer. Returns False if no such handle.

Parameters:: name (str)
Return type:: bool

automation_file.core.progress.progress_clear()[source]

Drop every finished transfer from the registry.

Return type:: int

automation_file.core.progress.progress_list()[source]

Snapshot of every registered transfer.

Return type:: list[dict[str, Any]]

automation_file.core.progress.register_progress_ops(registry)[source]

Wire FA_progress_* actions into an ActionRegistry.

Parameters:: registry (Any)
Return type:: None