Transforming futures: f_map, f_flat_map, MapExecutor, FlatMapExecutor

The output value of a future can be mapped to other values using a provided function.

Futures API

more_executors.f_map(future, fn=None, error_fn=None)

Map the output value of a future using the given functions.

Signature: Future<A>, fn<A⟶B> ⟶ Future<B>

Parameters

  • future (Future) – Any future.

  • fn (callable) – Any callable to be applied on successful futures. This function is provided the result of the input future.

  • error_fn (callable) – Any callable to be applied on unsuccessful futures. This function is provided the exception of the input future.

Returns

Future

A future resolved with:

  • the returned value of fn(future.result())

  • or the returned value of error_fn(future.exception())

  • or with the exception raised by future, fn or error_fn.

New in version 1.19.0.

Changed in version 2.2.0: Introduced error_fn.

more_executors.f_flat_map(future, fn=None, error_fn=None)

Map the output value of a future using the given future-returning functions.

Like f_map(), except that the mapping functions must return a future, and that future will be flattened into the output value (avoiding a nested future).

Signature: Future<A>, fn<A⟶Future<B>> ⟶ Future<B>

Parameters

  • future (Future) – Any future.

  • fn (callable) – Any future-returning callable to be applied on successful futures. This function is provided the result of the input future.

  • error_fn (callable) – Any future-returning callable to be applied on unsuccessful futures. This function is provided the exception of the input future.

Returns

Future

A future which is:

  • equivalent to that returned by fn if input future succeeded

  • or equivalent to that returned by error_fn if input future failed

  • or resolved with an exception if any of future, fn or error_fn failed

New in version 1.19.0.

Changed in version 2.2.0: Introduced error_fn.

Executors API

class more_executors.MapExecutor(delegate, fn=None, logger=None, name='default', **kwargs)

An executor which delegates to another executor while mapping output values/exceptions through given functions.

Parameters

  • delegate (Executor) – an executor to which callables will be submitted

  • fn (callable) –

    a callable applied to transform returned values of successful futures.

    This callable will be invoked with a single argument: the result() returned from a successful future.

    If omitted, no transformation occurs on result().

  • error_fn (callable) –

    a callable applied to transform returned values of unsuccessful futures.

    This callable will be invoked with a single argument: the exception() returned from a failed future.

    If omitted, no transformation occurs on exception().

  • logger (Logger) – a logger used for messages from this executor

  • name (str) – a name for this executor

Changed in version 2.2.0: Introduced error_fn.

Changed in version 2.7.0: Introduced name.

classmethod Executors.with_map(executor, fn=None, error_fn=None, logger=None)
Returns

a new executor which will transform results through the given function

Return type

MapExecutor

class more_executors.FlatMapExecutor(delegate, fn=None, logger=None, name='default', **kwargs)

An executor which delegates to another executor while mapping output values through given future-producing functions.

This executor behaves like MapExecutor, except that the given mapping/error functions must return instances of Future, and the mapped future is flattened into the future returned from this executor. This allows chaining multiple future-producing functions into a single future.

  • If the map/error function returns a Future, the result/exception of that future will be propagated to the future returned by this executor.

  • If the map/error function returns any other type, the returned future will fail with a TypeError.

  • If the map/error function raises an exception, the returned future will fail with that exception.

Parameters

  • delegate (Executor) – an executor to which callables will be submitted

  • fn (callable) –

    a callable applied to transform returned values of successful futures.

    This callable will be invoked with a single argument: the result() returned from a successful future.

    If omitted, no transformation occurs on result().

  • error_fn (callable) –

    a callable applied to transform returned values of unsuccessful futures.

    This callable will be invoked with a single argument: the exception() returned from a failed future.

    If omitted, no transformation occurs on exception().

  • logger (Logger) – a logger used for messages from this executor

  • name (str) – a name for this executor

Changed in version 2.2.0: Introduced error_fn.

Changed in version 2.7.0: Introduced name.

classmethod Executors.with_flat_map(executor, fn=None, error_fn=None, logger=None)
Returns

a new executor which will transform results through the given Future-providing function

Return type

FlatMapExecutor

New in version 1.12.0.