satella.coding.concurrent.futures package

Submodules

satella.coding.concurrent.futures.call_in_future module

satella.coding.concurrent.futures.call_in_future.call_in_future(executor, function, *args, **kwargs)

Return a callable, whose calling will schedule function to be executed on a target Executor.

The returned function will accept any number of arguments and keyword arguments, but will simply ignore them.

Parameters:
  • executor (Executor) – executor to run at

  • function (Callable) – callable to schedule

  • args – arguments to provide to the callable

  • kwargs – keyword arguments to provide to the callable

Returns:

a callable, calling which will schedule function to run at executor. Calling this callable will return the Future for that function

Return type:

Callable[[], Future]

satella.coding.concurrent.futures.collection module

class satella.coding.concurrent.futures.collection.FutureCollection(futures=())

Bases: object

A set of futures sharing a common result, or a common exception.

This overloads the operator + for making an union of futures. It can be used with either instances of FutureCollection or normal futures.

Also supports the indexing operator to get n-th future.

Parameters:

futures (Sequence[Future]) –

add(future)

Add a future

Parameters:

future (Future) – a Future to add

Returns:

self

Return type:

FutureCollection

add_done_callback(callback, only_one=False)

Add a callback to a Future to be called on it’s completion.

By default, this will add the callback to all futures.

Parameters:
  • callback – callback that takes the completed Future as argument

  • only_one (bool) – callback will be added only to a single Future. False by default

Raises:

IndexError – only_one was given and no Futures in collection!

Return type:

None

cancel()

Cancel all futures

Returns:

True if all sections were cancelled

Return type:

bool

exception(timeout=None)

Return first exception raised by any of the futures

This will block until the results are available. This call proceeding does not mean that results for all are available, since this will return the first exception encountered!

Parameters:

timeout (Optional[float]) – a timeout in seconds for a single result. Default value None means wait as long as necessary

Returns:

the first exception, or None if there were no exceptions

Raises:

WouldWaitMore – timeout while waiting for result

Return type:

Optional[Exception]

futures
result(timeout=None)

Return the result of all futures, as a list.

This will block until the results are available.

Parameters:

timeout (Optional[float]) – a timeout in seconds for a single result. Default value None means wait as long as necessary

Returns:

list containing results of all futures

Raises:

WouldWaitMore – timeout while waiting for result

Return type:

list

set_exception(exc)

Set an exception for all futures

Parameters:

exc – exception instance to set

Return type:

None

set_result(result)

Set a result for all futures

Parameters:

result – result to set

Return type:

None

set_running_or_notify_cancel()

Call set_running_or_notify_cancel on the futures

This will return True if at least one future was not cancelled

Return type:

bool

satella.coding.concurrent.futures.futures module

class satella.coding.concurrent.futures.futures.Future

Bases: Future, Generic[T]

A future that allows it’s callback handlers to change it’s result before presenting it to the user.

Use like this:

>>> fut = Future()
>>> fut.set_running_or_notify_cancel()
>>> def transform_future(future):
>>>     future.set_result(future.result() + 2)
>>> fut.add_pre_done_callback(transform_future)
>>> fut.set_result(2)
>>> assert fut.result() == 4

Initializes the future. Should not be called by clients.

add_pre_done_callback(fn)

Attaches a callable that will be called just before the future finishes and can change the future’s result (or insert an Exception).

Args:
fn: A callable that will be called with this future as its only

argument just before the future completes or is cancelled.

chain(fun)

Schedule function to be called with the result of this future as it’s argument (or exception value if the future excepted).

Parameters:

fun – function to call

Returns:

self

Return type:

Future

exception(timeout)

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

Args:
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.

Parameters:

timeout (None) –

Return type:

Type[Exception]

on_failure(fun)

Schedule function to be called with the exception value that befall this future

Parameters:

fun – function to call

Returns:

self

on_success(fun)

Schedule function to be called with the result of this future as it’s argument only if this future succeeds.

Parameters:

fun – function to call

Returns:

self

Return type:

Future

result(timeout=None)

Return the result of the call that the future represents.

Args:
timeout: The number of seconds to wait for the result if the future

isn’t done. If None, then there is no limit on the wait time.

Returns:

The result of the call that the future represents.

Raises:

CancelledError: If the future was cancelled. TimeoutError: If the future didn’t finish executing before the given

timeout.

Exception: If the call raised then that exception will be raised.

Return type:

T

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.

Parameters:

result (T) –

Return type:

None

class satella.coding.concurrent.futures.futures.WrappingFuture(source_future)

Bases: Future

A Satella future wrapping an existing Python future.

Use like:

>> wrapped = WrappingFuture(existing_python_future)

Initializes the future. Should not be called by clients.

Parameters:

source_future (Future) –

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.

Return type:

bool

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.

Return type:

bool

satella.coding.concurrent.futures.futures.wrap_if(fut)

Wrap a future, if it isn’t already wrapped

Parameters:

fut (Union[Future, Future]) – either a Python Future or a Satella Future

Returns:

a Satella future

Return type:

Future

satella.coding.concurrent.futures.wrapped_executor module

class satella.coding.concurrent.futures.wrapped_executor.ExecutorWrapper(executor)

Bases: Executor

A wrapping for Python executors to return Satella futures instead of standard Python ones.

Parameters:

executor (Executor) –

shutdown(wait=True)

Clean-up the resources associated with the Executor.

It is safe to call this method several times. Otherwise, no other methods can be called after this one.

Args:
wait: If True then shutdown will not return until all running

futures have finished executing and the resources used by the executor have been reclaimed.

submit(fn, *args, **kwargs)

Submits a callable to be executed with the given arguments.

Schedules the callable to be executed as fn(*args, **kwargs) and returns a Future instance representing the execution of the callable.

Returns:

A Future representing the given call.

Return type:

Future

Module contents

class satella.coding.concurrent.futures.ExecutorWrapper(executor)

Bases: Executor

A wrapping for Python executors to return Satella futures instead of standard Python ones.

Parameters:

executor (Executor) –

shutdown(wait=True)

Clean-up the resources associated with the Executor.

It is safe to call this method several times. Otherwise, no other methods can be called after this one.

Args:
wait: If True then shutdown will not return until all running

futures have finished executing and the resources used by the executor have been reclaimed.

submit(fn, *args, **kwargs)

Submits a callable to be executed with the given arguments.

Schedules the callable to be executed as fn(*args, **kwargs) and returns a Future instance representing the execution of the callable.

Returns:

A Future representing the given call.

Return type:

Future

class satella.coding.concurrent.futures.Future

Bases: Future, Generic[T]

A future that allows it’s callback handlers to change it’s result before presenting it to the user.

Use like this:

>>> fut = Future()
>>> fut.set_running_or_notify_cancel()
>>> def transform_future(future):
>>>     future.set_result(future.result() + 2)
>>> fut.add_pre_done_callback(transform_future)
>>> fut.set_result(2)
>>> assert fut.result() == 4

Initializes the future. Should not be called by clients.

add_pre_done_callback(fn)

Attaches a callable that will be called just before the future finishes and can change the future’s result (or insert an Exception).

Args:
fn: A callable that will be called with this future as its only

argument just before the future completes or is cancelled.

chain(fun)

Schedule function to be called with the result of this future as it’s argument (or exception value if the future excepted).

Parameters:

fun – function to call

Returns:

self

Return type:

Future

exception(timeout)

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

Args:
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.

Parameters:

timeout (None) –

Return type:

Type[Exception]

on_failure(fun)

Schedule function to be called with the exception value that befall this future

Parameters:

fun – function to call

Returns:

self

on_success(fun)

Schedule function to be called with the result of this future as it’s argument only if this future succeeds.

Parameters:

fun – function to call

Returns:

self

Return type:

Future

result(timeout=None)

Return the result of the call that the future represents.

Args:
timeout: The number of seconds to wait for the result if the future

isn’t done. If None, then there is no limit on the wait time.

Returns:

The result of the call that the future represents.

Raises:

CancelledError: If the future was cancelled. TimeoutError: If the future didn’t finish executing before the given

timeout.

Exception: If the call raised then that exception will be raised.

Return type:

T

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.

Parameters:

result (T) –

Return type:

None

class satella.coding.concurrent.futures.FutureCollection(futures=())

Bases: object

A set of futures sharing a common result, or a common exception.

This overloads the operator + for making an union of futures. It can be used with either instances of FutureCollection or normal futures.

Also supports the indexing operator to get n-th future.

Parameters:

futures (Sequence[Future]) –

add(future)

Add a future

Parameters:

future (Future) – a Future to add

Returns:

self

Return type:

FutureCollection

add_done_callback(callback, only_one=False)

Add a callback to a Future to be called on it’s completion.

By default, this will add the callback to all futures.

Parameters:
  • callback – callback that takes the completed Future as argument

  • only_one (bool) – callback will be added only to a single Future. False by default

Raises:

IndexError – only_one was given and no Futures in collection!

Return type:

None

cancel()

Cancel all futures

Returns:

True if all sections were cancelled

Return type:

bool

exception(timeout=None)

Return first exception raised by any of the futures

This will block until the results are available. This call proceeding does not mean that results for all are available, since this will return the first exception encountered!

Parameters:

timeout (Optional[float]) – a timeout in seconds for a single result. Default value None means wait as long as necessary

Returns:

the first exception, or None if there were no exceptions

Raises:

WouldWaitMore – timeout while waiting for result

Return type:

Optional[Exception]

futures
result(timeout=None)

Return the result of all futures, as a list.

This will block until the results are available.

Parameters:

timeout (Optional[float]) – a timeout in seconds for a single result. Default value None means wait as long as necessary

Returns:

list containing results of all futures

Raises:

WouldWaitMore – timeout while waiting for result

Return type:

list

set_exception(exc)

Set an exception for all futures

Parameters:

exc – exception instance to set

Return type:

None

set_result(result)

Set a result for all futures

Parameters:

result – result to set

Return type:

None

set_running_or_notify_cancel()

Call set_running_or_notify_cancel on the futures

This will return True if at least one future was not cancelled

Return type:

bool

exception satella.coding.concurrent.futures.InvalidStateError

Bases: Error

The operation is not allowed in this state.

class satella.coding.concurrent.futures.WrappingFuture(source_future)

Bases: Future

A Satella future wrapping an existing Python future.

Use like:

>> wrapped = WrappingFuture(existing_python_future)

Initializes the future. Should not be called by clients.

Parameters:

source_future (Future) –

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.

Return type:

bool

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.

Return type:

bool

satella.coding.concurrent.futures.call_in_future(executor, function, *args, **kwargs)

Return a callable, whose calling will schedule function to be executed on a target Executor.

The returned function will accept any number of arguments and keyword arguments, but will simply ignore them.

Parameters:
  • executor (Executor) – executor to run at

  • function (Callable) – callable to schedule

  • args – arguments to provide to the callable

  • kwargs – keyword arguments to provide to the callable

Returns:

a callable, calling which will schedule function to run at executor. Calling this callable will return the Future for that function

Return type:

Callable[[], Future]

satella.coding.concurrent.futures.wrap_if(fut)

Wrap a future, if it isn’t already wrapped

Parameters:

fut (Union[Future, Future]) – either a Python Future or a Satella Future

Returns:

a Satella future

Return type:

Future