diff options
| author | robot-piglet <[email protected]> | 2023-11-12 21:25:31 +0300 |
|---|---|---|
| committer | robot-piglet <[email protected]> | 2023-11-12 21:39:54 +0300 |
| commit | d28c55ab25cc8cedab8a5f4736c0d66e88b3da95 (patch) | |
| tree | 73d373709b74fa2baaa4fe02a40a77c0a5baf6b7 /contrib/python/httpcore/README.md | |
| parent | 35b17f4f3b6e0ed855e7e47d3f1eb57470388a2c (diff) | |
Intermediate changes
Diffstat (limited to 'contrib/python/httpcore/README.md')
| -rw-r--r-- | contrib/python/httpcore/README.md | 91 |
1 files changed, 91 insertions, 0 deletions
diff --git a/contrib/python/httpcore/README.md b/contrib/python/httpcore/README.md new file mode 100644 index 00000000000..66a21500169 --- /dev/null +++ b/contrib/python/httpcore/README.md @@ -0,0 +1,91 @@ +# HTTP Core + +[](https://github.com/encode/httpcore/actions) +[](https://pypi.org/project/httpcore/) + +> *Do one thing, and do it well.* + +The HTTP Core package provides a minimal low-level HTTP client, which does +one thing only. Sending HTTP requests. + +It does not provide any high level model abstractions over the API, +does not handle redirects, multipart uploads, building authentication headers, +transparent HTTP caching, URL parsing, session cookie handling, +content or charset decoding, handling JSON, environment based configuration +defaults, or any of that Jazz. + +Some things HTTP Core does do: + +* Sending HTTP requests. +* Thread-safe / task-safe connection pooling. +* HTTP(S) proxy & SOCKS proxy support. +* Supports HTTP/1.1 and HTTP/2. +* Provides both sync and async interfaces. +* Async backend support for `asyncio` and `trio`. + +## Requirements + +Python 3.8+ + +## Installation + +For HTTP/1.1 only support, install with: + +```shell +$ pip install httpcore +``` + +For HTTP/1.1 and HTTP/2 support, install with: + +```shell +$ pip install httpcore[http2] +``` + +For SOCKS proxy support, install with: + +```shell +$ pip install httpcore[socks] +``` + +# Sending requests + +Send an HTTP request: + +```python +import httpcore + +response = httpcore.request("GET", "https://www.example.com/") + +print(response) +# <Response [200]> +print(response.status) +# 200 +print(response.headers) +# [(b'Accept-Ranges', b'bytes'), (b'Age', b'557328'), (b'Cache-Control', b'max-age=604800'), ...] +print(response.content) +# b'<!doctype html>\n<html>\n<head>\n<title>Example Domain</title>\n\n<meta charset="utf-8"/>\n ...' +``` + +The top-level `httpcore.request()` function is provided for convenience. In practice whenever you're working with `httpcore` you'll want to use the connection pooling functionality that it provides. + +```python +import httpcore + +http = httpcore.ConnectionPool() +response = http.request("GET", "https://www.example.com/") +``` + +Once you're ready to get going, [head over to the documentation](https://www.encode.io/httpcore/). + +## Motivation + +You *probably* don't want to be using HTTP Core directly. It might make sense if +you're writing something like a proxy service in Python, and you just want +something at the lowest possible level, but more typically you'll want to use +a higher level client library, such as `httpx`. + +The motivation for `httpcore` is: + +* To provide a reusable low-level client library, that other packages can then build on top of. +* To provide a *really clear interface split* between the networking code and client logic, + so that each is easier to understand and reason about in isolation. |