{"id":2261,"library":"requests-futures","title":"Asynchronous Python HTTP for Humans","description":"Requests-futures is a small add-on for the popular 'requests' HTTP library, enabling asynchronous HTTP requests. It leverages Python's `concurrent.futures` module to perform requests concurrently using either `ThreadPoolExecutor` or `ProcessPoolExecutor`. It provides a `FuturesSession` class that mimics `requests.Session` but returns `Future` objects, allowing non-blocking operations and retrieval of responses later. The current version is 1.0.2, and its release cadence is infrequent but active.","status":"active","version":"1.0.2","language":"en","source_language":"en","source_url":"https://github.com/ross/requests-futures","tags":["http","asynchronous","concurrent","requests","futures","threading","multiprocessing","io-bound"],"install":[{"cmd":"pip install requests-futures","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core functionality relies on the 'requests' library's API and session management.","package":"requests"},{"reason":"Backport of concurrent.futures for Python versions older than 3.2 (automatically handled if on modern Python).","package":"futures","optional":true}],"imports":[{"symbol":"FuturesSession","correct":"from requests_futures.sessions import FuturesSession"}],"quickstart":{"code":"from requests_futures.sessions import FuturesSession\nimport os\n\nsession = FuturesSession()\n\n# Example: Send multiple GET requests concurrently\nurls = [\n    'http://httpbin.org/get?id=1',\n    'http://httpbin.org/get?id=2',\n    'http://httpbin.org/get?id=3',\n]\n\nfutures = [session.get(url) for url in urls]\n\nfor i, future in enumerate(futures):\n    try:\n        response = future.result() # Blocks until the request completes\n        print(f\"Request {i+1} Status: {response.status_code}\")\n        print(f\"Request {i+1} Content: {response.json()['args']}\")\n    except Exception as e:\n        print(f\"Request {i+1} failed: {e}\")\n","lang":"python","description":"Initialize a FuturesSession, submit requests which return Future objects, then iterate through the Futures and call `.result()` to obtain the Response objects once they are ready. Error handling for network issues should wrap the `.result()` call."},"warnings":[{"fix":"Ensure all components (session, request data, hooks) are picklable. For Python 3.4 using `ProcessPoolExecutor`, instantiate `FuturesSession(executor=ProcessPoolExecutor(), session=requests.Session())`. Python 3.5+ handles this more gracefully.","message":"Using `ProcessPoolExecutor` requires careful handling of pickling for the session and request objects. Python 2.x and < 3.4 are not supported for `ProcessPoolExecutor`. For Python 3.4+, an existing `requests.Session` instance *must* be passed when initializing `FuturesSession` with a `ProcessPoolExecutor`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Wrap calls to `future.result()` in a `try/except` block to catch network errors or other request-related exceptions.","message":"Exceptions are not raised immediately when a request is made. Instead, they are 'shifted' to when `future.result()` is called. This changes the expected location for `try/except` blocks.","severity":"breaking","affected_versions":"All versions"},{"fix":"Always explicitly set `max_workers` when initializing `FuturesSession` with `ThreadPoolExecutor` to ensure predictable concurrency levels, e.g., `FuturesSession(executor=ThreadPoolExecutor(max_workers=10))`.","message":"The default number of workers for the `ThreadPoolExecutor` has changed. Older versions might have defaulted to 2 workers, while recent versions (e.g., 1.0.2) default to 8 workers.","severity":"gotcha","affected_versions":"<1.0.0 (potentially)"},{"fix":"Always specify a `timeout` when making requests, e.g., `session.get(url, timeout=5)`. This timeout applies to `future.result()` as well.","message":"As with standard `requests`, omitting `timeout` parameters can lead to requests hanging indefinitely, especially critical in concurrent applications where one stalled request can impact many others.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}