{"id":8728,"library":"treq","title":"Treq","description":"Treq is a high-level HTTP client library for Python, inspired by the popular `requests` library but built upon Twisted's asynchronous networking framework. It simplifies making HTTP requests within Twisted applications by providing a familiar, easy-to-use API for various HTTP methods, JSON handling, and cookie management. The library is actively maintained, currently at version 25.5.0, with a regular release cadence to support new Python and Twisted versions.","status":"active","version":"25.5.0","language":"en","source_language":"en","source_url":"https://github.com/twisted/treq","tags":["HTTP client","Twisted","asynchronous","networking"],"install":[{"cmd":"pip install treq","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Treq is built on top of Twisted's asynchronous event loop and networking components (Agents).","package":"Twisted","optional":false},{"reason":"Used for URL representation and manipulation within treq's API.","package":"hyperlink","optional":false}],"imports":[{"symbol":"get","correct":"import treq\n# ... await treq.get(...)"},{"symbol":"post","correct":"import treq\n# ... await treq.post(...)"},{"note":"`task.react` is the recommended way to run Twisted applications, handling reactor startup and shutdown automatically.","wrong":"from twisted.internet import reactor; reactor.run()","symbol":"react","correct":"from twisted.internet.task import react"},{"note":"Used for advanced customization of the underlying Twisted Agent.","symbol":"HTTPClient","correct":"from treq.client import HTTPClient"}],"quickstart":{"code":"from twisted.internet.task import react\nimport treq\nimport os\n\nasync def fetch_and_print(reactor):\n    # Using httpbin.org for a simple test endpoint\n    response = await treq.get(\"https://httpbin.org/get\", reactor=reactor)\n    print(f\"Status: {response.code} {response.phrase.decode()}\")\n    print(\"Headers:\")\n    for k, v in response.headers.getAllRawHeaders():\n        print(f\"  {k.decode()}: {', '.join(map(bytes.decode, v))}\")\n    body = await response.text()\n    print(\"Body:\")\n    print(body)\n\nif __name__ == '__main__':\n    react(fetch_and_print)\n","lang":"python","description":"This example demonstrates how to perform a basic GET request using `treq` and print the response status, headers, and body. It uses `twisted.internet.task.react` to manage the Twisted reactor, ensuring the asynchronous operation runs correctly and the application exits gracefully."},"warnings":[{"fix":"Use either `json` for JSON payloads or `files`/`data` for form-encoded or multipart data, but not both simultaneously.","message":"Mixing the `json` argument with `files` or `data` in a single request is no longer allowed and will raise a `TypeError`.","severity":"breaking","affected_versions":">=24.9.0"},{"fix":"Upgrade to Python 3.8+ and ensure your Twisted installation is up-to-date (22.10.0 or newer for treq 25.5.0). Consult the treq changelog for specific version compatibility.","message":"Support for Python 3.6 was dropped in treq 22.2.0. Support for Python 3.7 and PyPy 3.7/3.8 was deprecated and subsequently removed in later releases (e.g., 23.11.0, 25.5.0). The minimum supported Twisted version has also been incremented over time, currently requiring >=22.10.0 for treq 25.5.0.","severity":"deprecated","affected_versions":">=22.2.0"},{"fix":"Upgrade to treq 22.1.0 or newer to ensure correct cookie handling and prevent unintended information disclosure.","message":"A security vulnerability (CVE-2022-23607) in versions prior to 22.1.0 caused cookies provided as a dictionary to be sent to *all* domains on redirect, potentially exposing sensitive information.","severity":"gotcha","affected_versions":"<22.1.0"},{"fix":"Upgrade to treq 20.4.0 or newer. Ensure all string inputs are properly encoded if dealing with older versions, or explicitly use `hyperlink` objects for robust URL construction.","message":"Prior to version 20.4.0, the `params` argument had issues with URL-encoding characters like `&` or `#`, and non-ASCII URLs/parameters could lead to `UnicodeEncodeError`.","severity":"gotcha","affected_versions":"<20.4.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Choose only one method for sending the request body: either `json={...}` for a JSON payload, or `data={...}` for form-encoded data, or `files={...}` for multipart file uploads. Do not combine them.","cause":"Attempting to send both a JSON payload and form data (or files) in a single HTTP request, which is a breaking change introduced in treq 24.9.0.","error":"TypeError: mixing 'json' with 'files' or 'data' is not allowed"},{"fix":"Ensure your application runs within the Twisted reactor. Use `twisted.internet.task.react(your_main_function)` to properly start and stop the reactor for your asynchronous code.","cause":"The Twisted reactor (event loop) was not started or stopped prematurely, preventing network operations from completing.","error":"twisted.internet.error.HostnameResolutionError: DNS lookup failed"},{"fix":"Upgrade treq to version 20.4.0 or newer. If stuck on an older version, manually encode URL components using `urllib.parse.quote` or `hyperlink` before passing them to treq.","cause":"Sending non-ASCII characters in URLs or query parameters with older versions of treq (prior to 20.4.0) that had encoding issues.","error":"UnicodeEncodeError: 'ascii' codec can't encode character..."},{"fix":"Ensure you are awaiting the content retrieval methods (e.g., `body = await response.text()`) and only `decode()` raw `bytes` objects obtained from `await response.content()`.","cause":"Attempting to call `.decode()` on a response body that might already be a string (e.g., from `response.text()` or `response.json()`), or forgetting to await `response.text()`/`response.json()` and operating on a Deferred.","error":"AttributeError: 'bytes' object has no attribute 'decode'"}]}