0
# treq
1

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

4
## Package Information
5

6
- **Package Name**: treq
7
- **Language**: Python
8
- **Installation**: `pip install treq`
9

10
## Core Imports
11

12
```python
13
import treq
14
```
15

16
Common import pattern for main HTTP functions:
17

18
```python
19
from treq import get, post, put, delete, patch, head, request
20
```
21

22
Content processing functions:
23

24
```python
25
from treq import collect, content, text_content, json_content
26
```
27

28
## Basic Usage
29

30
```python
31
import treq
32
from twisted.internet import defer, reactor
33

34
@defer.inlineCallbacks
35
def example():
36
    # Make a simple GET request
37
    response = yield treq.get('https://httpbin.org/get')
38
    body = yield response.text()
39
    print("Response:", body)
40
    
41
    # POST with JSON data
42
    response = yield treq.post(
43
        'https://httpbin.org/post',
44
        json={'key': 'value'}
45
    )
46
    data = yield response.json()
47
    print("Posted data:", data['json'])
48
    
49
    # POST with form data
50
    response = yield treq.post(
51
        'https://httpbin.org/post',
52
        data={'name': 'example', 'value': '123'}
53
    )
54
    
55
    # Request with authentication
56
    response = yield treq.get(
57
        'https://httpbin.org/basic-auth/user/pass',
58
        auth=('user', 'pass')
59
    )
60
    
61
    reactor.stop()
62

63
# Start the example
64
example()
65
reactor.run()
66
```
67

68
## Architecture
69

70
treq provides a layered architecture:
71

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

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

80
## Capabilities
81

82
### HTTP Request Methods
83

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

86
```python { .api }
87
def get(url, headers=None, **kwargs): ...
88
def post(url, data=None, **kwargs): ...  
89
def put(url, data=None, **kwargs): ...
90
def patch(url, data=None, **kwargs): ...
91
def delete(url, **kwargs): ...
92
def head(url, **kwargs): ...
93
def request(method, url, **kwargs): ...
94
```
95

96
[HTTP Requests](./http-requests.md)
97

98
### Response Content Processing
99

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

102
```python { .api }
103
def collect(response, collector): ...
104
def content(response): ...
105
def text_content(response, encoding="ISO-8859-1"): ...
106
def json_content(response, **kwargs): ...
107
```
108

109
[Content Processing](./content-processing.md)
110

111
### HTTP Client Class
112

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

115
```python { .api }
116
class HTTPClient:
117
    def __init__(self, agent, cookiejar=None, data_to_body_producer=IBodyProducer): ...
118
    def request(self, method, url, **kwargs): ...
119
    def get(self, url, **kwargs): ...
120
    def post(self, url, data=None, **kwargs): ...
121
```
122

123
[HTTP Client](./http-client.md)
124

125
### Authentication Support
126

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

129
```python { .api }
130
def add_basic_auth(agent, username, password): ...
131
def add_auth(agent, auth_config): ...
132
```
133

134
[Authentication](./authentication.md)
135

136
### Testing Utilities
137

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

140
```python { .api }
141
class StubTreq:
142
    def __init__(self, resource): ...
143
    # Provides all HTTP methods: get, post, put, delete, patch, head
144
    def flush(self): ...
145

146
class RequestTraversalAgent: ...
147
class StringStubbingResource: ...
148
```
149

150
[Testing](./testing.md)
151

152
### Cookie Management
153

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

156
```python { .api }
157
def scoped_cookie(origin, name, value): ...
158
def search(jar, *, domain, name=None): ...
159
```
160

161
[Cookies](./cookies.md)
162

163
## Types
164

165
Core type definitions used throughout the API:
166

167
```python { .api }
168
# URL types
169
_URLType = Union[str, bytes, EncodedURL, DecodedURL]
170

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

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

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

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

183
# JSON data
184
_JSONType = Any
185
```