{"id":6651,"library":"futurist","title":"Futurist","description":"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.","status":"active","version":"3.3.0","language":"en","source_language":"en","source_url":"https://github.com/openstack/futurist","tags":["asynchronous","futures","thread-pool","process-pool","openstack","concurrency","statistics"],"install":[{"cmd":"pip install futurist","lang":"bash","label":"Install stable release"}],"dependencies":[],"imports":[{"note":"A primary executor for concurrent operations, extending concurrent.futures.ThreadPoolExecutor with added features like statistics.","symbol":"ThreadPoolExecutor","correct":"from futurist import ThreadPoolExecutor"},{"note":"An executor for concurrent operations using processes, extending concurrent.futures.ProcessPoolExecutor.","symbol":"ProcessPoolExecutor","correct":"from futurist import ProcessPoolExecutor"},{"note":"Provides statistics about tasks submitted and executed by a Futurist executor. Accessible via the 'statistics' property of executors.","symbol":"ExecutorStatistics","correct":"from futurist.ext.futures import ExecutorStatistics"}],"quickstart":{"code":"import time\nfrom futurist import ThreadPoolExecutor\n\ndef my_task(value):\n    \"\"\"A simple task to demonstrate execution and statistics.\"\"\"\n    time.sleep(0.01) # Simulate some work\n    return value * 2\n\nif __name__ == \"__main__\":\n    # Initialize ThreadPoolExecutor with a maximum of 2 workers\n    with ThreadPoolExecutor(max_workers=2) as executor:\n        print(\"Submitting tasks...\")\n        # Submit 5 tasks to the executor\n        futures = [executor.submit(my_task, i) for i in range(5)]\n\n        # Retrieve results from completed futures\n        results = [f.result() for f in futures]\n        print(f\"Results: {results}\")\n\n        # Access and print execution statistics\n        stats = executor.statistics\n        print(f\"Executed tasks: {stats.executed}\")\n        print(f\"Failed tasks: {stats.failures}\")\n        print(f\"Cancelled tasks: {stats.cancelled}\")\n        print(f\"Total runtime: {stats.runtime:.4f}s\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Always verify you are consulting the official OpenStack `futurist` documentation, typically found at `docs.openstack.org/futurist/` or the `openstack/futurist` GitHub repository.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}