executorlib.standalone.select.FutureSelector

class executorlib.standalone.select.FutureSelector(future: Future, selector: int | str)

Bases: Future

A Future wrapper that returns a single element from a result that is a tuple, list, or dict.

This is used by split_future() and get_item_from_future() to give callers an individual Future-like object for each output of a function that returns a collection.

Parameters:

• future (Future) – The underlying future whose result is a collection.

• selector (int | str) – Index (for sequences) or key (for mappings) used to extract the desired element from the result.

__init__(future: Future, selector: int | str)

Parameters:

• future (Future) – The underlying future whose result is a collection.

• selector (int | str) – Index or key used to extract an element from the result.

Methods

__init__(future, selector)
add_done_callback(fn)	Attaches a callable that will be called when the future finishes.
cancel()	Cancel the future if possible.
cancelled()	Return True if the future was cancelled.
done()	Return True if the future was cancelled or finished executing.
exception([timeout])	Return the exception raised by the call that the future represents.
result([timeout])	Return the selected element from the underlying future's result.
running()	Return True if the future is currently executing.
set_exception(exception)	Sets the result of the future as being the given exception.
set_result(result)	Sets the return value of work associated with the future.
set_running_or_notify_cancel()	Mark the future as running or process any cancel notifications.

add_done_callback(fn)

Attaches a callable that will be called when the future finishes.

Parameters:

fn – A callable that will be called with this future as its only argument when the future completes or is cancelled. The callable will always be called by a thread in the same process in which it was added. If the future has already completed or been cancelled then the callable will be called immediately. These callables are called in the order that they were added.

cancel()

Cancel the future if possible.

Returns True if the future was cancelled, False otherwise. A future cannot be cancelled if it is running or has already completed.

cancelled()

Return True if the future was cancelled.

done()

Return True if the future was cancelled or finished executing.

exception(timeout=None)

Return the exception raised by the call that the future represents.

Parameters:

timeout – The number of seconds to wait for the exception if the future isn’t done. If None, then there is no limit on the wait time.

Returns:

The exception raised by the call that the future represents or None if the call completed without raising.

Raises:

• CancelledError – If the future was cancelled.

• TimeoutError – If the future didn’t finish executing before the given timeout.

result(timeout: float | None = None) → Any

Return the selected element from the underlying future’s result.

Parameters:

timeout (float, optional) – Maximum seconds to wait for the result. Defaults to None (wait indefinitely).

Returns:

The element at position/key selector in the underlying result, or None if

the underlying result is None.

Return type:

Any

running()

Return True if the future is currently executing.

set_exception(exception)

Sets the result of the future as being the given exception.

Should only be used by Executor implementations and unit tests.

set_result(result)

Sets the return value of work associated with the future.

Should only be used by Executor implementations and unit tests.

set_running_or_notify_cancel()

Mark the future as running or process any cancel notifications.

Should only be used by Executor implementations and unit tests.

If the future has been cancelled (cancel() was called and returned True) then any threads waiting on the future completing (though calls to as_completed() or wait()) are notified and False is returned.

If the future was not cancelled then it is put in the running state (future calls to running() will return True) and True is returned.

This method should be called by Executor implementations before executing the work associated with this future. If this method returns False then the work should not be executed.

Returns:

False if the Future was cancelled, True otherwise.

Raises:

RuntimeError – if this method was already called or if set_result() or set_exception() was called.