Treq

Common errors

• TypeError: mixing 'json' with 'files' or 'data' is not allowed

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

• twisted.internet.error.HostnameResolutionError: DNS lookup failed

  cause The Twisted reactor (event loop) was not started or stopped prematurely, preventing network operations from completing.
  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.

• UnicodeEncodeError: 'ascii' codec can't encode character...

  cause Sending non-ASCII characters in URLs or query parameters with older versions of treq (prior to 20.4.0) that had encoding issues.
  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.

• AttributeError: 'bytes' object has no attribute 'decode'

  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.
  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()`.

Warnings

• breaking Mixing the `json` argument with `files` or `data` in a single request is no longer allowed and will raise a `TypeError`.
  Fix: Use either `json` for JSON payloads or `files`/`data` for form-encoded or multipart data, but not both simultaneously.
• deprecated 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.
  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.
• gotcha 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.
  Fix: Upgrade to treq 22.1.0 or newer to ensure correct cookie handling and prevent unintended information disclosure.
• gotcha 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`.
  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.

Install

• pip install treq Install latest version

Imports

• get

  import treq
  # ... await treq.get(...)

• post

  import treq
  # ... await treq.post(...)

• react
  wrong:

  from twisted.internet import reactor; reactor.run()

  correct:

  from twisted.internet.task import react

  `task.react` is the recommended way to run Twisted applications, handling reactor startup and shutdown automatically.
• HTTPClient

  from treq.client import HTTPClient

  Used for advanced customization of the underlying Twisted Agent.

Quickstart

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.

from twisted.internet.task import react
import treq
import os

async def fetch_and_print(reactor):
    # Using httpbin.org for a simple test endpoint
    response = await treq.get("https://httpbin.org/get", reactor=reactor)
    print(f"Status: {response.code} {response.phrase.decode()}")
    print("Headers:")
    for k, v in response.headers.getAllRawHeaders():
        print(f"  {k.decode()}: {', '.join(map(bytes.decode, v))}")
    body = await response.text()
    print("Body:")
    print(body)

if __name__ == '__main__':
    react(fetch_and_print)