{"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":"python","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,"search_vec":"'3.3.0':43 'activ':46 'addit':12 'aim':15 'asynchron':21,53 'cadenc':52 'concurr':62 'concurrent.futures':14 'current':40 'enhanc':18 'eventlet':33 'execut':23 'executor':31,34,37 'featur':26 'futur':54 'futurist':1,2 'gather':29 'includ':25 'librari':6 'like':27 'maintain':47 'offer':17 'openstack':8,61 'pool':57,60 'process':59 'process-pool':58 'provid':10 'python':5 'regular':50 'releas':51 'statist':28,63 'synchron':36 'thread':56 'thread-pool':55 'transpar':19 'use':11 'version':42 'work':22","created_at":"2026-04-15T18:37:04.410906+00:00","updated_at":"2026-04-16T15:12:54.169533+00:00","problems":[{"fix":"Avoid using `eventlet.monkey_patch()` when working with `ProcessPoolExecutor`. If eventlet is required, consider using `futurist.GreenThreadPoolExecutor` (if your tasks are I/O bound and compatible) or carefully manage when and what parts of eventlet are monkey-patched, or consider migrating to native Python threading/asyncio where possible, as eventlet support in `futurist` is being deprecated for some components.","cause":"Using `eventlet.monkey_patch()` in combination with `concurrent.futures.ProcessPoolExecutor` (or `futurist`'s `ProcessPoolExecutor` which inherits from it) can lead to deadlocks or hanging processes due to conflicts in how they manage concurrency and I/O.","error":"eventlet hangs when using futures.ProcessPoolExecutor"},{"fix":"Always retrieve the result of a submitted `Future` object using `future.result()` within a `try-except` block, or call `future.exception()` to check for and handle any exceptions that occurred in the worker thread. Iterate over futures using `concurrent.futures.as_completed` for robust error handling.","cause":"Exceptions raised within tasks submitted to `ThreadPoolExecutor` (and thus `futurist`'s executors) are 'swallowed' by default and stored within the `Future` object; they are not automatically re-raised in the main thread unless `future.result()` or `future.exception()` is explicitly called on the completed future.","error":"ThreadPoolExecutor doesn't print errors"},{"fix":"To get the result of a `Future` object, call its `.result()` method. If you need to process results as they complete from multiple futures, use `concurrent.futures.as_completed()`.","cause":"This error occurs when attempting to iterate directly over a `Future` object returned by `executor.submit()`. A `Future` object is not an iterable; it's a proxy for the eventual result of an asynchronous operation.","error":"TypeError: cannot unpack non-iterable Future object"},{"fix":"Install the `futurist` library using pip: `pip install futurist`. Ensure you are running your code with the same Python interpreter where the library was installed.","cause":"The `futurist` library is not installed in your current Python environment or the Python interpreter cannot find it.","error":"ModuleNotFoundError: No module named 'futurist'"},{"fix":"Import the specific executor class directly from the `futurist` library, for example: `from futurist import ThreadPoolExecutor`. Then you can instantiate it as `executor = ThreadPoolExecutor()`. Check the `futurist` documentation for the correct import path of the specific class you intend to use.","cause":"This error often happens when you try to call a module directly as if it were a class or function. For example, if you import `futurist` and then try `futurist.ThreadPoolExecutor()`, but `ThreadPoolExecutor` is a class nested within `futurist`, you need to import it specifically.","error":"TypeError: 'module' object is not callable (e.g., futurist.ThreadPoolExecutor())"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.3.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://docs.openstack.org/futurist","github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/futurist/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["workflow","http-networking","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}