Futurist

3.3.0 · active · verified Wed Apr 15

Futurist is a Python library from OpenStack that provides useful additions to `concurrent.futures`, aiming to offer enhanced transparency in asynchronous work execution. It includes features like statistics gathering for executors, an eventlet executor, a synchronous executor, and more. Currently at version 3.3.0, it is actively maintained with a regular release cadence.

Warnings

gotcha Do not confuse `futurist` (from OpenStack, extending `concurrent.futures`) with `python-future` (a compatibility library for Python 2/3). They serve entirely different purposes, and their usage patterns are distinct. Searching for 'futurist quickstart' may sometimes lead to `python-future` documentation, which is incorrect for this library.
Fix: Always verify you are consulting the official OpenStack `futurist` documentation, typically found at `docs.openstack.org/futurist/` or the `openstack/futurist` GitHub repository.
gotcha The `futurist.ThreadPoolExecutor` (like `concurrent.futures.ThreadPoolExecutor`) does not shrink its thread pool once it has expanded. The pool will eventually reach its `max_workers` capacity and remain at that size for its lifetime, which can lead to higher memory consumption if many temporary workers are created.
Fix: If dynamic pool sizing is required, consider `futurist.DynamicThreadPoolExecutor` (if available and suitable for your version) or manage thread pool lifecycles explicitly. For applications with highly variable workloads, be mindful of `max_workers` setting.
gotcha When using `futurist.ProcessPoolExecutor`, be aware of limitations inherited from `concurrent.futures.ProcessPoolExecutor`, particularly on Windows. Processes cannot be spawned directly if a main module has importable code (e.g., global statements outside of an `if __name__ == '__main__':` block).
Fix: Ensure that the code which creates and uses the `ProcessPoolExecutor` (and any functions it executes) is protected by `if __name__ == '__main__':` guards, especially on Windows.

Install

pip install futurist Install stable release

Imports

ThreadPoolExecutor
```
from futurist import ThreadPoolExecutor
```
A primary executor for concurrent operations, extending concurrent.futures.ThreadPoolExecutor with added features like statistics.
ProcessPoolExecutor
```
from futurist import ProcessPoolExecutor
```
An executor for concurrent operations using processes, extending concurrent.futures.ProcessPoolExecutor.
ExecutorStatistics
```
from futurist.ext.futures import ExecutorStatistics
```
Provides statistics about tasks submitted and executed by a Futurist executor. Accessible via the 'statistics' property of executors.

Quickstart

This quickstart demonstrates how to use `futurist.ThreadPoolExecutor` to run tasks concurrently and collect execution statistics. It submits multiple tasks, waits for their completion, retrieves results, and then displays the executor's performance metrics.

import time
from futurist import ThreadPoolExecutor

def my_task(value):
    """A simple task to demonstrate execution and statistics."""
    time.sleep(0.01) # Simulate some work
    return value * 2

if __name__ == "__main__":
    # Initialize ThreadPoolExecutor with a maximum of 2 workers
    with ThreadPoolExecutor(max_workers=2) as executor:
        print("Submitting tasks...")
        # Submit 5 tasks to the executor
        futures = [executor.submit(my_task, i) for i in range(5)]

        # Retrieve results from completed futures
        results = [f.result() for f in futures]
        print(f"Results: {results}")

        # Access and print execution statistics
        stats = executor.statistics
        print(f"Executed tasks: {stats.executed}")
        print(f"Failed tasks: {stats.failures}")
        print(f"Cancelled tasks: {stats.cancelled}")
        print(f"Total runtime: {stats.runtime:.4f}s")

view raw JSON →