From c1401ebfe10a0f728f8e88139c7a1f6d2441cd94 Mon Sep 17 00:00:00 2001
From: Tom Christie <tom@tomchristie.com>
Date: Tue, 18 Jan 2022 11:44:32 +0000
Subject: [PATCH] Version 0.14.5 (#482)

---
 CHANGELOG.md         |  6 +++++
 docs/index.md        | 12 +++++++---
 docs/proxies.md      | 54 +++++++++++++++++++++++++++++++++++++++-----
 httpcore/__init__.py |  2 +-
 4 files changed, 64 insertions(+), 10 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0159d396..4695196e 100644
--- a/CHANGELOG.md
+++ b/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)
diff --git a/docs/index.md b/docs/index.md
index 4ed3733c..f54ffd5f 100644
--- a/docs/index.md
+++ b/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:
diff --git a/docs/proxies.md b/docs/proxies.md
index bb59cf1e..b2ff8dbf 100644
--- a/docs/proxies.md
+++ b/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/")
+```
 
 ---
 
diff --git a/httpcore/__init__.py b/httpcore/__init__.py
index a3b73e62..4a27d7c2 100644
--- a/httpcore/__init__.py
+++ b/httpcore/__init__.py
@@ -82,7 +82,7 @@
     "WriteError",
 ]
 
-__version__ = "0.14.4"
+__version__ = "0.14.5"
 
 
 __locals = locals()