0
# HTTP Client
1

2
HTTPie's HTTP client module provides low-level functions for building and sending HTTP requests programmatically.
3

4
```python
5
from httpie.client import collect_messages, build_requests_session, make_request_kwargs, make_send_kwargs, finalize_headers
6
from httpie.context import Environment
7
from httpie.models import RequestsMessage
8
from typing import Iterable, Callable
9
import argparse
10
import requests
11
```
12

13
## Capabilities
14

15
### Message Collection
16

17
Core function for collecting HTTP request and response messages.
18

19
```python { .api }
20
def collect_messages(
21
    env: Environment,
22
    args: argparse.Namespace,
23
    request_body_read_callback: Callable[[bytes], None] = None,
24
) -> Iterable[RequestsMessage]:
25
    """
26
    Core message collection and HTTP execution.
27
    
28
    Args:
29
        env: HTTPie environment instance
30
        args: Parsed command-line arguments
31
        request_body_read_callback: Optional callback for request body streaming
32
        
33
    Yields:
34
        RequestsMessage: HTTP request and response messages
35
    """
36
```
37

38
### Session Building
39

40
Functions for building HTTP sessions with custom configurations.
41

42
```python { .api }
43
def build_requests_session(
44
    session_name: str = None,
45
    config_dir: str = None,
46
    read_only: bool = False,
47
    **session_kwargs
48
) -> requests.Session:
49
    """
50
    Build a requests session with HTTPie configurations.
51
    
52
    Args:
53
        session_name: Name of persistent session
54
        config_dir: Configuration directory path
55
        read_only: Whether session should be read-only
56
        **session_kwargs: Additional session configuration
57
        
58
    Returns:
59
        requests.Session: Configured HTTP session
60
    """
61
```
62

63
### Request Preparation
64

65
Utilities for preparing HTTP request parameters.
66

67
```python { .api }
68
def make_request_kwargs(
69
    args: argparse.Namespace,
70
    base_headers: dict = None
71
) -> dict:
72
    """
73
    Build keyword arguments for requests.request().
74
    
75
    Args:
76
        args: Parsed command-line arguments
77
        base_headers: Base headers to include
78
        
79
    Returns:
80
        dict: Request keyword arguments
81
    """
82

83
def make_send_kwargs(args: argparse.Namespace) -> dict:
84
    """
85
    Build keyword arguments for session.send().
86
    
87
    Args:
88
        args: Parsed command-line arguments
89
        
90
    Returns:
91
        dict: Send keyword arguments
92
    """
93

94
def finalize_headers(headers: dict) -> dict:
95
    """
96
    Finalize headers before sending request.
97
    
98
    Args:
99
        headers: Request headers dictionary
100
        
101
    Returns:
102
        dict: Finalized headers
103
    """
104
```
105

106
### Usage Examples
107

108
#### Basic Message Collection
109

110
```python
111
from httpie.core import main
112
from httpie.client import collect_messages
113
from httpie.context import Environment
114
from httpie.cli.definition import parser
115

116
# Parse arguments
117
env = Environment()
118
args = parser.parse_args(['GET', 'httpie.io/hello'], env=env)
119

120
# Collect messages
121
for message in collect_messages(env, args):
122
    if hasattr(message, 'status_code'):
123
        print(f"Response: {message.status_code}")
124
    else:
125
        print(f"Request: {message.method}")
126
```
127

128
#### Custom Session Building
129

130
```python
131
from httpie.client import build_requests_session
132

133
# Build session with custom configuration
134
session = build_requests_session(
135
    session_name='api-client',
136
    timeout=30,
137
    verify=True
138
)
139

140
# Use session for requests
141
response = session.get('https://api.example.com/data')
142
```
143

144
#### Request Preparation
145

146
```python
147
from httpie.client import make_request_kwargs
148
from httpie.cli.definition import parser
149
from httpie.context import Environment
150

151
# Parse arguments
152
env = Environment()
153
args = parser.parse_args(['POST', 'api.example.com', 'name=John'], env=env)
154

155
# Prepare request kwargs
156
request_kwargs = make_request_kwargs(args)
157
print(f"Method: {request_kwargs['method']}")
158
print(f"URL: {request_kwargs['url']}")
159
print(f"Data: {request_kwargs.get('data', 'None')}")
160
```