Version 0.14.5 (#482)

CHANGELOG.md

@@ -4,6 +4,12 @@ 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.5 (January 18th, 2022)
+
+- SOCKS proxy support. (#478)
+- Add proxy_auth argument to HTTPProxy (#481)
+- Improve error message on 'RemoteProtocolError' exception when server disconnects without sending a response (#479)
+
 ## 0.14.4 (January 5th, 2022)
 
 - Support HTTP/2 on HTTPS tunnelling proxies. (#468)

docs/index.md

@@ -18,25 +18,31 @@ Some things HTTP Core does do:
 
 * Sending HTTP requests.
 * Thread-safe / task-safe connection pooling.
-* HTTP(S) proxy support.
+* 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`.
 
 ## Installation
 
-For HTTP/1.1 only support, install with...
+For HTTP/1.1 only support, install with:
 
 ```shell
 $ pip install httpcore
 ```
 
-For HTTP/1.1 and HTTP/2 support, install with...
+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]
+```
+
 ## Example
 
 Let's check we're able to send HTTP requests:

docs/proxies.md

@@ -1,6 +1,6 @@
 # Proxies
 
-The `httpcore` package currently provides support for HTTP proxies, using either "HTTP Forwarding" and "HTTP Tunnelling". Forwarding is a proxy mechanism for sending requests to `http` URLs via an intermediate proxy. Tunnelling is a proxy mechanism for sending requests to `https` URLs via an intermediate proxy.
+The `httpcore` package provides support for HTTP proxies, using either "HTTP Forwarding" or "HTTP Tunnelling". Forwarding is a proxy mechanism for sending requests to `http` URLs via an intermediate proxy. Tunnelling is a proxy mechanism for sending requests to `https` URLs via an intermediate proxy.
 
 Sending requests via a proxy is very similar to sending requests using a standard connection pool:
 
@@ -25,22 +25,64 @@ Requests will automatically use either forwarding or tunnelling, depending on if
 
 ## Authentication
 
-Proxy headers can be included in the initial configuration:
+Proxy authentication can be included in the initial configuration:
+
+```python
+import httpcore
+
+# A `Proxy-Authorization` header will be included on the initial proxy connection.
+proxy = httpcore.HTTPProxy(
+    proxy_url="http://127.0.0.1:8080/",
+    proxy_auth=("<username", "password")
+)
+```
+
+Custom headers can also be included:
 
 ```python
 import httpcore
 import base64
 
-auth = base64.b64encode(b"Basic <username>:<password>")
+# Construct and include a `Proxy-Authorization` header.
+auth = base64.b64encode(b"<username>:<password>")
 proxy = httpcore.HTTPProxy(
     proxy_url="http://127.0.0.1:8080/",
-    proxy_headers={"Proxy-Authorization": auth}
+    proxy_headers={"Proxy-Authorization": b"Basic " + auth}
 )
 ```
 
-## HTTP Versions
+## Proxy SSL and HTTP Versions
+
+Proxy support currently only allows for HTTP/1.1 connections to the proxy,
+and does not currently support SSL proxy connections, which require HTTPS-in-HTTPS,
+
+## SOCKS proxy support
+
+The `httpcore` package also supports proxies using the SOCKS protocol.
+
+Make sure to install the optional dependancy using `pip install httpcore[socks]`.
+
+The `SOCKSProxy` class should be using instead of a standard connection pool:
 
-Proxy support currently only allows for HTTP/1.1 connections to the proxy.
+```python
+import httpcore
+
+# Note that the SOCKS port is 1080.
+proxy = httpcore.SOCKSProxy(proxy_url="socks://127.0.0.1:1080/")
+r = proxy.request("GET", "https://www.example.com/")
+```
+
+Authentication via SOCKS is also supported:
+
+```python
+import httpcore
+
+proxy = httpcore.SOCKSProxy(
+    proxy_url="socks://127.0.0.1:8080/",
+    proxy_auth=("<username", "password")
+)
+r = proxy.request("GET", "https://www.example.com/")
+```
 
 ---
 

httpcore/__init__.py

@@ -82,7 +82,7 @@
     "WriteError",
 ]
 
-__version__ = "0.14.4"
+__version__ = "0.14.5"
 
 
 __locals = locals()