0
# HTTPie
1

2
HTTPie is a modern, user-friendly command-line HTTP client designed for the API era. It provides an intuitive syntax for creating and sending arbitrary HTTP requests with formatted and colorized output, making it ideal for testing, debugging, and interacting with APIs and HTTP servers.
3

4
## Package Information
5

6
- **Package Name**: httpie
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install httpie`
10

11
## Core Imports
12

13
For programmatic usage:
14

15
```python
16
import httpie
17
from httpie.core import main, raw_main, program, collect_messages
18
from httpie.context import Environment
19
from httpie.status import ExitStatus
20
from httpie.models import RequestsMessage
21
from httpie.sessions import get_httpie_session, Session
22
from httpie.config import Config
23
```
24

25
Plugin development:
26

27
```python
28
from httpie.plugins import AuthPlugin, FormatterPlugin, ConverterPlugin, TransportPlugin
29
from httpie.plugins.base import BasePlugin
30
```
31

32
## Basic Usage
33

34
### Command Line Interface
35

36
HTTPie provides three main command-line utilities:
37

38
```bash
39
# Basic GET request
40
http httpie.io/hello
41

42
# Custom HTTP method with headers and JSON data
43
http PUT pie.dev/put X-API-Token:123 name=John
44

45
# POST with form data
46
http --form POST pie.dev/post name=John email=john@example.com
47

48
# Download a file
49
http --download https://example.com/file.zip
50

51
# Authentication
52
http -a username:password httpie.io/basic-auth/username/password
53

54
# Sessions (preserve cookies and auth)
55
http --session=logged-in -a username:password pie.dev/basic-auth/username/password
56
http --session=logged-in pie.dev/cookies
57
```
58

59
### Programmatic Usage
60

61
```python
62
import sys
63
from httpie.core import main
64
from httpie.context import Environment
65

66
# Create environment
67
env = Environment()
68

69
# Make HTTP request programmatically
70
exit_status = main(['http', 'httpie.io/hello'], env)
71

72
if exit_status == 0:
73
    print("Request successful")
74
else:
75
    print(f"Request failed with status: {exit_status}")
76
```
77

78
## Architecture
79

80
HTTPie follows a modular architecture with several key components:
81

82
- **Core Engine**: Main request processing and argument parsing (`httpie.core`)
83
- **CLI Interface**: Command-line argument definition and parsing (`httpie.cli`)
84
- **HTTP Client**: Request/response handling built on Python requests (`httpie.client`)
85
- **Output System**: Formatting and display of HTTP messages (`httpie.output`)
86
- **Plugin System**: Extensible architecture for auth, formatting, and transport (`httpie.plugins`)
87
- **Session Management**: Persistent session storage and retrieval (`httpie.sessions`)
88
- **Manager Interface**: HTTPie package and plugin management (`httpie.manager`)
89

90
## Capabilities
91

92
### Command-Line HTTP Client
93

94
The primary interface providing `http`, `https`, and `httpie` commands for making HTTP requests with human-friendly syntax, automatic JSON support, and rich output formatting.
95

96
```python { .api }
97
def main(args: List[Union[str, bytes]] = sys.argv, env: Environment = Environment()) -> ExitStatus:
98
    """Main HTTPie function that processes command-line arguments and executes HTTP requests."""
99

100
def raw_main(parser: argparse.ArgumentParser, main_program: Callable[[argparse.Namespace, Environment], ExitStatus], args: List[Union[str, bytes]] = sys.argv, env: Environment = Environment(), use_default_options: bool = True) -> ExitStatus:
101
    """Core main function with error handling and plugin loading."""
102

103
def program(args: argparse.Namespace, env: Environment) -> ExitStatus:
104
    """The main program without error handling."""
105

106
def collect_messages(env: Environment, args: argparse.Namespace, request_body_read_callback: Callable[[bytes], None] = None) -> Iterable[RequestsMessage]:
107
    """Core message collection and HTTP execution."""
108
```
109

110
[Command-Line Interface](./cli.md)
111

112
### HTTP Client
113

114
Low-level HTTP client functions for building and sending requests programmatically, including message collection, session building, and request preparation utilities.
115

116
```python { .api }
117
def build_requests_session(session_name: str = None, config_dir: str = None, read_only: bool = False, **session_kwargs) -> requests.Session:
118
    """Build a requests session with HTTPie configurations."""
119

120
def make_request_kwargs(args: argparse.Namespace, base_headers: dict = None) -> dict:
121
    """Build keyword arguments for requests.request()."""
122

123
def make_send_kwargs(args: argparse.Namespace) -> dict:
124
    """Build keyword arguments for session.send()."""
125
```
126

127
[HTTP Client](./client.md)
128

129
### Plugin Development
130

131
Extensible plugin system supporting authentication, output formatting, content conversion, and custom transport adapters.
132

133
```python { .api }
134
class AuthPlugin(BasePlugin):
135
    auth_type: str
136
    def get_auth(self, username: str = None, password: str = None): ...
137

138
class FormatterPlugin(BasePlugin):
139
    def format_headers(self, headers: str) -> str: ...
140
    def format_body(self, content: str, mime: str) -> str: ...
141

142
class ConverterPlugin(BasePlugin):
143
    def convert(self, body: bytes) -> Tuple[str, str]: ...
144

145
class TransportPlugin(BasePlugin):
146
    prefix: str
147
    def get_adapter(self): ...
148
```
149

150
[Plugin Development](./plugins.md)
151

152
### Session Management
153

154
Persistent session storage for maintaining cookies, authentication, and custom request settings across multiple HTTP requests.
155

156
```python { .api }
157
class Session:
158
    def load(self) -> Dict[str, Any]: ...
159
    def save(self) -> None: ...
160
    def delete(self) -> None: ...
161

162
def get_httpie_session(env: Environment, config_dir: Path, session_name: str, host: Optional[str], url: str, *, suppress_legacy_warnings: bool = False) -> Session:
163
    """Get or create a HTTPie session for persistent data storage."""
164
```
165

166
[Session Management](./sessions.md)
167

168
### Configuration Management
169

170
Configuration system for managing HTTPie settings, default options, and plugin directories.
171

172
```python { .api }
173
class Config:
174
    default_options: List[str]
175
    plugins_dir: str
176
    
177
def get_default_config_dir() -> str:
178
    """Get the default HTTPie configuration directory."""
179
```
180

181
[Configuration](./configuration.md)
182

183
### HTTP Models and Status
184

185
Data models for HTTP requests/responses and comprehensive exit status codes for different scenarios.
186

187
```python { .api }
188
class ExitStatus(IntEnum):
189
    SUCCESS = 0
190
    ERROR = 1
191
    ERROR_TIMEOUT = 2
192
    ERROR_HTTP_3XX = 3
193
    ERROR_HTTP_4XX = 4
194
    ERROR_HTTP_5XX = 5
195
    ERROR_TOO_MANY_REDIRECTS = 6
196
    PLUGIN_ERROR = 7
197
    ERROR_CTRL_C = 130
198

199
def http_status_to_exit_status(http_status: int, follow: bool = False) -> ExitStatus:
200
    """Convert HTTP status code to HTTPie exit status."""
201
```
202

203
[HTTP Models](./models.md)
204

205
### Constants and Utilities
206

207
HTTP processing constants, utility functions, and helper classes for request parsing, output formatting, and data handling.
208

209
```python { .api }
210
# HTTP method constants
211
HTTP_GET: str = 'GET'
212
HTTP_POST: str = 'POST'
213
HTTP_OPTIONS: str = 'OPTIONS'
214

215
# Output option constants
216
OUT_REQ_HEAD: str = 'H'
217
OUT_REQ_BODY: str = 'B'  
218
OUT_RESP_HEAD: str = 'h'
219
OUT_RESP_BODY: str = 'b'
220
OUT_RESP_META: str = 'm'
221

222
# Utility functions
223
def humanize_bytes(n: int, precision: int = 2) -> str: ...
224
def get_content_type(filename: str) -> str: ...
225
def split_cookies(cookie_header: str) -> List[str]: ...
226
```
227

228
[Constants and Utilities](./utilities.md)
229

230
## Types
231

232
```python { .api }
233
from typing import List, Union, Optional, Callable, Iterable, Dict, Any, IO, Tuple
234
from pathlib import Path
235
import argparse
236

237
class Environment:
238
    """HTTPie execution environment containing stdin/stdout/stderr and configuration."""
239
    program_name: str
240
    stdin_encoding: str
241
    is_windows: bool
242
    config: Config
243
    stdin: IO
244
    stdout: IO
245
    stderr: IO
246

247
class RequestsMessage:
248
    """HTTP request or response message wrapper."""
249
    
250
class OutputOptions:
251
    """Configuration for what parts of HTTP messages to output."""
252
    
253
class ProcessingOptions:
254
    """Configuration for how to process and format output."""
255

256
class Config:
257
    """HTTPie configuration management."""
258
    default_options: List[str]
259
    plugins_dir: Path
260

261
class Session:
262
    """HTTPie session for persistent request data."""
263
    def load(self) -> Dict[str, Any]: ...
264
    def save(self) -> None: ...
265
    def delete(self) -> None: ...
266
```