httpcore 0.14 redesign (#420)

* httpcore 0.14 redesign * Add types-certifi to requirements * Run unasync * Make tests more liberal when inspecting 'stream.get_extra_info(socket)' * Make tests more liberal when inspecting 'stream.get_extra_info(socket)' * Drop unused import * Update test matrix from '3.10.0-beta.4' to '3.10' * Update docs * Update requirements * Update README, docs * Update CHANGELOG * py.typed * Minor docs tweak * Update CHANGELOG
encode · Nov 11, 2021 · f9b9391 · f9b9391
1 parent 85a1f9e
commit f9b9391
Show file tree

Hide file tree

Showing 103 changed files with 7,793 additions and 8,555 deletions.
diff --git a/.github/workflows/test-suite.yml b/.github/workflows/test-suite.yml
@@ -14,7 +14,7 @@ jobs:
 
     strategy:
       matrix:
-        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10.0-beta.4"]
+        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10"]
 
     steps:
       - uses: "actions/checkout@v2"

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## 0.14.0
+
+The 0.14 release is a complete reworking of `httpcore`, comprehensively addressing some underlying issues in the connection pooling, as well as substantially redesigning the API to be more user friendly.
+
+Some of the lower-level API design also makes the components more easily testable in isolation, and the package now has 100% test coverage.
+
+See [discussion #419](https://github.com/encode/httpcore/discussions/419) for a little more background.
+
+There's some other neat bits in there too, such as the "trace" extension, which gives a hook into inspecting the internal events that occur during the request/response cycle. This extension is needed for the HTTPX cli, in order to...
+
+* Log the point at which the connection is established, and the IP/port on which it is made.
+* Determine if the outgoing request should log as HTTP/1.1 or HTTP/2, rather than having to assume it's HTTP/2 if the --http2 flag was passed. (Which may not actually be true.)
+* Log SSL version info / certificate info.
+
+Note that `curio` support is not currently available in 0.14.0. If you're using `httpcore` with `curio` please get in touch, so we can assess if we ought to prioritize it as a feature or not.
+
 ## 0.13.7 (September 13th, 2021)
 
 - Fix broken error messaging when URL scheme is missing, or a non HTTP(S) scheme is used. (Pull #403)

diff --git a/README.md b/README.md
@@ -17,61 +17,59 @@ defaults, or any of that Jazz.
 Some things HTTP Core does do:
 
 * Sending HTTP requests.
-* Provides both sync and async interfaces.
-* Supports HTTP/1.1 and HTTP/2.
-* Async backend support for `asyncio`, `trio` and `curio`.
-* Automatic connection pooling.
+* Thread-safe / task-safe connection pooling.
 * HTTP(S) proxy support.
+* Supports HTTP/1.1 and HTTP/2.
+* Provides both sync and async interfaces.
+* Async backend support for `asyncio` and `trio`.
 
 ## Installation
 
 For HTTP/1.1 only support, install with...
 
 ```shell
-$ pip install httpcore
+$ pip install git+https://github.com/encode/httpcore
 ```
 
 For HTTP/1.1 and HTTP/2 support, install with...
 
 ```shell
-$ pip install httpcore[http2]
+$ pip install git+https://github.com/encode/httpcore[http2]
 ```
 
-## Quickstart
+# Sending requests
 
-Here's an example of making an HTTP GET request using `httpcore`...
+Send an HTTP request:
 
 ```python
-with httpcore.SyncConnectionPool() as http:
-    status_code, headers, stream, extensions = http.handle_request(
-        method=b'GET',
-        url=(b'https', b'example.org', 443, b'/'),
-        headers=[(b'host', b'example.org'), (b'user-agent', b'httpcore')],
-        stream=httpcore.ByteStream(b''),
-        extensions={}
-    )
-    body = stream.read()
-    print(status_code, body)
+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 ...'
 ```
 
-Or, using async...
+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
-async with httpcore.AsyncConnectionPool() as http:
-    status_code, headers, stream, extensions = await http.handle_async_request(
-        method=b'GET',
-        url=(b'https', b'example.org', 443, b'/'),
-        headers=[(b'host', b'example.org'), (b'user-agent', b'httpcore')],
-        stream=httpcore.ByteStream(b''),
-        extensions={}
-    )
-    body = await stream.aread()
-    print(status_code, body)
+import httpcore
+
+pool = httpcore.ConnectionPool()
+response = pool.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 *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`.

diff --git a/docs/api.md b/docs/api.md