tessl/pypi-treq

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

treq

Name: tessl/pypi-treq
Author: tessl

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

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