Registry / http-networking / requests-futures

requests-futures

library1.0.2pypypi✓ verified 26d ago

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.

http-networking

pip install requests-futures

github ↗package ↗

INSTALL

IMPORT

SIG · REQUESTS-FUTURES

requests-futures

http-networkingpythonv1.0.2

Install

2.1s avg

Import

431ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.450s · 21.1MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.1s · import 0.412s · 22MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

FuturesSession

✓ from requests_futures.sessions import FuturesSession

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.

from requests_futures.sessions import FuturesSession import os session = FuturesSession() # Example: Send multiple GET requests concurrently urls = [ 'http://httpbin.org/get?id=1', 'http://httpbin.org/get?id=2', 'http://httpbin.org/get?id=3', ] futures = [session.get(url) for url in urls] for i, future in enumerate(futures): try: response = future.result() # Blocks until the request completes print(f"Request {i+1} Status: {response.status_code}") print(f"Request {i+1} Content: {response.json()['args']}") except Exception as e: print(f"Request {i+1} failed: {e}")

Debug

Known issues

gotchaUsing `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`.

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.

affects: All versions

breakingExceptions 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.

fix

Wrap calls to `future.result()` in a `try/except` block to catch network errors or other request-related exceptions.

affects: All versions

gotchaThe 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.

fix

Always explicitly set `max_workers` when initializing `FuturesSession` with `ThreadPoolExecutor` to ensure predictable concurrency levels, e.g., `FuturesSession(executor=ThreadPoolExecutor(max_workers=10))`.

affects: <1.0.0 (potentially)

gotchaAs 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.

fix

Always specify a `timeout` when making requests, e.g., `session.get(url, timeout=5)`. This timeout applies to `future.result()` as well.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'requests_futures'

The 'requests-futures' library has not been installed in the current Python environment.

fix

pip install requests-futures

AttributeError: 'Future' object has no attribute 'status_code'

Methods like `FuturesSession.get()` return a `Future` object, not a `requests.Response` object directly. You must call `.result()` on the `Future` to get the actual `Response`.

fix

future = session.get(url)
response = future.result()
print(response.status_code)

AttributeError: module 'requests_futures' has no attribute 'FuturesSession'

The `FuturesSession` class resides within the `sessions` submodule of the `requests_futures` package, not directly in the top-level package.

fix

from requests_futures.sessions import FuturesSession

Upgrade

Version history

1.0.2latest on PyPI · released Nov 15, 2024

Audit

Dependencies

requestsrequiredCore functionality relies on the 'requests' library's API and session management.

futuresoptionalBackport of concurrent.futures for Python versions older than 3.2 (automatically handled if on modern Python).

Agent activity

13 hits · last 30 days

node

Resources

githubhttps://github.com/ross/requests-futures ↗

packagehttps://pypi.org/project/requests-futures/ ↗