HTTP Client API Reference¶
Auto-generated API documentation for the HTTP client module.
httpclient
¶
Zero-dependency sync + async HTTP REST client.
Part of zerodep: https://github.com/Oaklight/zerodep Copyright (c) 2026 Peng Ding. MIT License.
Sync (http.client) and async (asyncio streams) HTTP/1.1 client for REST API consumption. Thread-safe by design.
Sync usage::
response = get("https://httpbin.org/get")
response.json()
Async usage::
response = await async_get("https://httpbin.org/get")
response.json()
Session usage::
with Client() as client:
r = client.get("https://httpbin.org/get")
async with AsyncClient() as client:
r = await client.get("https://httpbin.org/get")
CaseInsensitiveDict
¶
Bases: dict
Case-insensitive key lookup dict subclass that preserves original casing.
Provides case-insensitive HTTP header storage: d["Content-Type"]
and d["content-type"] resolve to the same slot, but iteration and
wire serialisation yield the original casing the caller supplied.
Internally the underlying dict stores {lowercase_key: value}
for O(1) lookups, while a parallel _keys mapping records
{lowercase_key: original_key} for casing-preserving iteration.
This is the type used for Response.headers,
StreamingResponse.headers, and the internal req_headers dict
that flows through _prepare_request. HTTP header names are
case-insensitive per :rfc:7230 §3.2, but the wire format and
echo tests expect the casing the caller supplied.
It is a dict subclass, so it is accepted everywhere a dict
is expected. Equality is case-insensitive on keys:
CaseInsensitiveDict({"X-Foo": "bar"}) == {"x-foo": "bar"}.
Source code in httpclient/httpclient.py
148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 | |
items()
¶
Yield (original_key, value) pairs; preserves casing on the wire.
HttpClientError
¶
HTTPError
¶
Bases: HttpClientError
Raised on non-2xx status when raise_for_status() is called.
Source code in httpclient/httpclient.py
TooManyRedirects
¶
HttpConnectionError
¶
Bases: HttpClientError
Raised on connection failures.
Attributes:
| Name | Type | Description |
|---|---|---|
host |
Remote hostname that the connection targeted. |
|
port |
Remote port number. |
|
message |
Human-readable error description. |
Source code in httpclient/httpclient.py
HttpTimeoutError
¶
Bases: HttpClientError
Raised on request timeout.
Attributes:
| Name | Type | Description |
|---|---|---|
url |
The URL that timed out. |
|
timeout |
The timeout value in seconds that was exceeded. |
|
message |
Human-readable error description. |
Source code in httpclient/httpclient.py
Socks5Error
¶
Bases: HttpConnectionError
Raised on SOCKS5 proxy handshake failures.
Source code in httpclient/httpclient.py
Response
¶
HTTP response object.
Attributes:
| Name | Type | Description |
|---|---|---|
status_code |
HTTP status code. |
|
headers |
Response headers as dict (last value wins for duplicates). |
|
content |
Raw response body as bytes. |
|
url |
Final URL after redirects. |
Source code in httpclient/httpclient.py
354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 | |
Auth
¶
Base class for HTTP authentication.
Source code in httpclient/httpclient.py
auth_headers(method, url)
¶
Return authorization headers.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
method
|
str
|
HTTP method. |
required |
url
|
str
|
Request URL. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, str]
|
Dict of headers to add to the request. |
Source code in httpclient/httpclient.py
BasicAuth
¶
Bases: Auth
HTTP Basic authentication.
Source code in httpclient/httpclient.py
auth_headers(method, url)
¶
Return Basic Authorization header.
DigestAuth
¶
Bases: Auth
HTTP Digest authentication.
Source code in httpclient/httpclient.py
auth_headers(method, url)
¶
auth_headers_from_challenge(method, path, challenge)
¶
Compute Digest auth headers from a WWW-Authenticate challenge.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
method
|
str
|
HTTP method. |
required |
path
|
str
|
Request path (URI). |
required |
challenge
|
str
|
The WWW-Authenticate header value. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, str]
|
Dict with the Authorization header. |
Source code in httpclient/httpclient.py
StreamingResponse
¶
HTTP streaming response -- holds the connection open.
Use as a context manager to ensure cleanup::
with get(url, stream=True) as r:
for chunk in r.iter_bytes():
process(chunk)
async with await async_get(url, stream=True) as r:
async for line in r.aiter_lines():
handle(line)
Source code in httpclient/httpclient.py
666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 | |
ok
property
¶
True if status_code is 2xx.
cookies
property
¶
Parse Set-Cookie headers into a {name: value} dict (cached).
raise_for_status()
¶
iter_bytes(chunk_size=4096)
¶
Yield response body in chunks.
Source code in httpclient/httpclient.py
iter_lines()
¶
Yield response body line by line (decoded).
Source code in httpclient/httpclient.py
read()
¶
aiter_bytes(chunk_size=4096)
async
¶
Async yield response body in chunks.
Source code in httpclient/httpclient.py
aiter_lines()
async
¶
Async yield response body line by line (decoded).
Source code in httpclient/httpclient.py
aread()
async
¶
close()
¶
Close the underlying connection (sync or async best-effort).
Source code in httpclient/httpclient.py
aclose()
async
¶
Close the underlying async connection.
Source code in httpclient/httpclient.py
Client
¶
Synchronous HTTP client session with connection pooling.
Thread-safe: the underlying connection pool uses its own
threading.Lock to protect shared state.
The cookie jar is a flat dict[str, str] — cookies are not
scoped by domain or path. This is suitable for single-origin use
(e.g. an API client talking to one service). For multi-origin
scenarios, manage cookies per-domain yourself.
Usage::
with Client(headers={"Authorization": "Bearer token"}) as c:
r = c.get("https://api.example.com/data")
Source code in httpclient/httpclient.py
3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 3266 3267 3268 3269 3270 3271 3272 3273 3274 3275 3276 3277 3278 3279 3280 3281 3282 3283 3284 3285 3286 3287 3288 3289 3290 3291 3292 3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306 3307 3308 3309 3310 3311 3312 3313 3314 3315 3316 3317 3318 3319 3320 3321 3322 3323 3324 3325 3326 3327 3328 3329 3330 3331 3332 3333 3334 3335 3336 3337 3338 3339 3340 3341 3342 3343 3344 | |
request(method, url, **kwargs)
¶
Send an HTTP request.
Source code in httpclient/httpclient.py
close()
¶
AsyncClient
¶
Asynchronous HTTP client session with connection pooling.
Safe for concurrent use from multiple asyncio tasks. The underlying
connection pool uses its own asyncio.Lock to protect shared state.
The cookie jar is a flat dict[str, str] — cookies are not
scoped by domain or path. This is suitable for single-origin use
(e.g. an API client talking to one service). For multi-origin
scenarios, manage cookies per-domain yourself.
Usage::
async with AsyncClient(headers={"Authorization": "Bearer token"}) as c:
r = await c.get("https://api.example.com/data")
Source code in httpclient/httpclient.py
3347 3348 3349 3350 3351 3352 3353 3354 3355 3356 3357 3358 3359 3360 3361 3362 3363 3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3374 3375 3376 3377 3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398 3399 3400 3401 3402 3403 3404 3405 3406 3407 3408 3409 3410 3411 3412 3413 3414 3415 3416 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 3427 3428 3429 3430 3431 3432 3433 3434 3435 3436 3437 3438 3439 3440 3441 3442 3443 3444 3445 3446 3447 3448 3449 3450 3451 3452 3453 3454 3455 3456 3457 3458 3459 | |
request(method, url, **kwargs)
async
¶
Send an async HTTP request.
Source code in httpclient/httpclient.py
aclose()
async
¶
close()
¶
Emit a warning and do nothing — use await aclose() instead.
AsyncClient manages async resources; calling synchronous close()
cannot safely await the pool teardown coroutine. This method exists
solely for interface parity with :class:Client so that type-annotated
code that calls client.close() does not raise AttributeError.
Always prefer :meth:aclose inside async code.
Source code in httpclient/httpclient.py
close_pools()
¶
Close every connection held by the default sync pool.
The module-level helpers keep connections open between calls, so a long-lived process can release them explicitly. Connections also close at process exit, and a forked child drops the sockets it inherited.
Source code in httpclient/httpclient.py
aclose_pools()
async
¶
Close the default async pool of the running event loop.
Source code in httpclient/httpclient.py
get(url, **kwargs)
¶
post(url, **kwargs)
¶
put(url, **kwargs)
¶
patch(url, **kwargs)
¶
delete(url, **kwargs)
¶
head(url, **kwargs)
¶
options(url, **kwargs)
¶
async_get(url, **kwargs)
async
¶
async_post(url, **kwargs)
async
¶
Send an async POST request.
async_put(url, **kwargs)
async
¶
async_patch(url, **kwargs)
async
¶
Send an async PATCH request.
async_delete(url, **kwargs)
async
¶
Send an async DELETE request.
async_head(url, **kwargs)
async
¶
Send an async HEAD request.
async_options(url, **kwargs)
async
¶
Send an async OPTIONS request.