doFolder.hashing.executor module

Executor module providing progress-aware thread pool execution capabilities.

This module implements a thread pool executor with built-in progress tracking functionality. It includes progress controllers, future wrappers, and utility functions for managing asynchronous tasks with progress reporting.

Added in version 2.3.0.

class doFolder.hashing.executor.FutureCanSync(runningFrom: Callable[[], bool] | None = None)

Bases: Future[_T]

Future that supports custom running state checking.

Extends the standard Future to allow custom logic for determining if the future is currently running.

running() → bool

Check if the future is currently running.

Returns:

True if the future is running, False otherwise.

runningFrom: Callable[[], bool] | None = None

class doFolder.hashing.executor.FutureWithProgress(*args, **kwargs)

Bases: FutureCanSync[_T], ProgressController

A Future that can report progress.

Combines the functionality of a Future with progress tracking capabilities. This allows asynchronous operations to report their progress while maintaining the standard Future interface.

statue: TaskStatus = 'waiting'

updateProgress(*args, **kwargs)

Update the progress value and optionally the total.

Notifies all registered listeners after updating the values.

Parameters:

• progress (int, optional) – The new progress value.

• total (int, optional) – The new total value. If None, keeps current total.

• add (int, optional) – The amount to add to the current progress. If None, keeps current progress.

class doFolder.hashing.executor.ProgressController

Bases: object

A controller for tracking and reporting progress of operations.

This class manages progress state and notifies listeners when progress changes. It maintains a current progress value and total, and can synchronize with other progress controllers.

_progress

Current progress value.

Type:

int

_total

Total value for the operation.

Type:

int

_listener

List of registered progress listeners.

Type:

List[ProgressListener]

addProgressListener(listener: Callable[[int, int, ProgressController], None]) → Callable[[], None]

Add a listener that will be called with the current progress.

The listener is immediately called with the current progress state.

Parameters:

listener (ProgressListener) – Function to call when progress updates. Takes (progress, total, controller) as parameters.

Returns:

Function to remove the listener when called.

Return type:

Callable[[], None]

historyTime: float = 3.0

property percent: float

Calculate completion percentage.

Returns:

Completion percentage as float (0.0 to 100.0).

property progress: int

Get current progress value.

Returns:

Current progress as integer.

property remain

Calculate estimated remaining time based on current speed.

Returns:

Estimated remaining time in seconds, or None if speed unavailable.

property speed

Calculate current processing speed based on history.

Returns:

Current speed in units per second, or None if insufficient data.

syncFrom(target: ProgressController)

Synchronize this controller’s progress with another controller.

Sets up a listener on the target controller that will update this controller’s progress whenever the target’s progress changes.

Parameters:

target (ProgressController) – The controller to synchronize from.

Returns:

Function to stop the synchronization.

Return type:

Callable[[], None]

property total: int

Get total progress target value.

Returns:

Total progress target as integer.

updateProgress(progress: int | None = None, *, total: int | None = None, add: int | None = None)

Update the progress value and optionally the total.

Notifies all registered listeners after updating the values.

Parameters:

• progress (int, optional) – The new progress value.

• total (int, optional) – The new total value. If None, keeps current total.

• add (int, optional) – The amount to add to the current progress. If None, keeps current progress.

class doFolder.hashing.executor.ThreadPoolExecutorWithProgress(max_workers=None, thread_name_prefix='', initializer=None, initargs=(), **ctxkwargs)

Bases: ThreadPoolExecutor

A thread pool executor that reports progress.

Extends the standard ThreadPoolExecutor to automatically provide progress tracking for submitted tasks. Each submitted task receives a ProgressController and returns a FutureWithProgress that can report progress updates.

submit(fn, /, *args, **kwargs) → FutureWithProgress

Submit a callable to be executed with the given arguments.

The callable will receive a ‘progressControler’ keyword argument that can be used to report progress during execution.

Parameters:

• fn – The callable to be executed.

• *args – Positional arguments to pass to the callable.

• **kwargs – Keyword arguments to pass to the callable.

Returns:

A Future that can report progress and will

resolve with the result of the callable.

Return type:

FutureWithProgress

doFolder.hashing.executor.futureMap(target: ~concurrent.futures._base.Future[~doFolder.hashing.executor._T], creater: ~collections.abc.Callable[[...], ~doFolder.hashing.executor._P] = <class 'doFolder.hashing.executor.FutureCanSync'>)

Map a Future to a new Future using a creator function.

Creates a new Future that will be resolved with the same result or exception as the target Future. This is useful for wrapping Futures with additional functionality.

Parameters:

• target (Future[_T]) – The source Future to map from.

• creater (Callable[[], _P]) – Function that creates the new Future. Defaults to Future[_T].

Returns:

The new Future created by the creater function.

Return type:

_P