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