or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mdcontent-processing.mdcookies.mdhttp-client.mdhttp-requests.mdindex.mdtesting.md
tile.json

tessl/pypi-treq

High-level Twisted HTTP Client API for asynchronous HTTP requests in Python

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/treq@25.5.x

To install, run

npx @tessl/cli install tessl/pypi-treq@25.5.0

index.mddocs/

treq

A high-level HTTP client library built on top of Twisted's asynchronous networking framework, providing a requests-like API for making HTTP requests in asynchronous Python applications. treq offers comprehensive HTTP method support, automatic content handling, authentication mechanisms, cookie management, and response streaming capabilities.

Package Information

  • Package Name: treq
  • Language: Python
  • Installation: pip install treq

Core Imports

import treq

Common import pattern for main HTTP functions:

from treq import get, post, put, delete, patch, head, request

Content processing functions:

from treq import collect, content, text_content, json_content

Basic Usage

import treq
from twisted.internet import defer, reactor

@defer.inlineCallbacks
def example():
    # Make a simple GET request
    response = yield treq.get('https://httpbin.org/get')
    body = yield response.text()
    print("Response:", body)
    
    # POST with JSON data
    response = yield treq.post(
        'https://httpbin.org/post',
        json={'key': 'value'}
    )
    data = yield response.json()
    print("Posted data:", data['json'])
    
    # POST with form data
    response = yield treq.post(
        'https://httpbin.org/post',
        data={'name': 'example', 'value': '123'}
    )
    
    # Request with authentication
    response = yield treq.get(
        'https://httpbin.org/basic-auth/user/pass',
        auth=('user', 'pass')
    )
    
    reactor.stop()

# Start the example
example()
reactor.run()

Architecture

treq provides a layered architecture:

  • High-level API (treq.*): Simple functions for common HTTP operations
  • HTTPClient: Core client class handling connection pooling and request lifecycle
  • Agent Integration: Built on Twisted's Agent system for maximum asynchronous performance
  • Content Processing: Streaming and buffered content handling with automatic encoding detection
  • Testing Support: In-memory testing utilities for mocking HTTP requests without network calls

This design integrates seamlessly with Twisted's reactor-based event loop and supports both callback-based and async/await programming patterns.

Capabilities

HTTP Request Methods

Core HTTP request functions supporting all standard methods with comprehensive parameter options for headers, authentication, cookies, timeouts, and data handling.

def get(url, headers=None, **kwargs): ...
def post(url, data=None, **kwargs): ...  
def put(url, data=None, **kwargs): ...
def patch(url, data=None, **kwargs): ...
def delete(url, **kwargs): ...
def head(url, **kwargs): ...
def request(method, url, **kwargs): ...

HTTP Requests

Response Content Processing

Functions for processing HTTP response content with support for streaming, buffered access, automatic encoding detection, and JSON parsing.

def collect(response, collector): ...
def content(response): ...
def text_content(response, encoding="ISO-8859-1"): ...
def json_content(response, **kwargs): ...

Content Processing

HTTP Client Class

Advanced HTTP client providing direct access to connection pooling, custom agents, and request lifecycle management for applications requiring fine-grained control.

class HTTPClient:
    def __init__(self, agent, cookiejar=None, data_to_body_producer=IBodyProducer): ...
    def request(self, method, url, **kwargs): ...
    def get(self, url, **kwargs): ...
    def post(self, url, data=None, **kwargs): ...

HTTP Client

Authentication Support

HTTP authentication mechanisms including Basic Auth with integration into the Agent architecture for secure credential handling.

def add_basic_auth(agent, username, password): ...
def add_auth(agent, auth_config): ...

Authentication

Testing Utilities

In-memory testing framework for mocking HTTP requests without network access, enabling fast and reliable unit tests for HTTP-based applications.

class StubTreq:
    def __init__(self, resource): ...
    # Provides all HTTP methods: get, post, put, delete, patch, head
    def flush(self): ...

class RequestTraversalAgent: ...
class StringStubbingResource: ...

Testing

Cookie Management

Cookie handling utilities for creating scoped cookies and managing cookie jars with proper domain and security attribute handling.

def scoped_cookie(origin, name, value): ...
def search(jar, *, domain, name=None): ...

Cookies

Types

Core type definitions used throughout the API:

# URL types
_URLType = Union[str, bytes, EncodedURL, DecodedURL]

# Request data types  
_DataType = Union[bytes, io.BytesIO, io.BufferedReader, IBodyProducer, Dict[str, str], List[Tuple[str, str]]]

# Headers types
_HeadersType = Union[Headers, Dict[Union[bytes, str], Union[bytes, str]], Dict[Union[bytes, str], List[Union[bytes, str]]]]

# Cookies types
_CookiesType = Union[CookieJar, Mapping[str, str]]

# Files for upload
_FilesType = Union[Mapping[str, _FileValue], Iterable[Tuple[str, _FileValue]]]

# JSON data
_JSONType = Any