Merge branch 'master' into master

Author: waketzheng

.github/CONTRIBUTING.md

@@ -211,9 +211,10 @@ this is where our previously generated `client.pem` comes in:
 ```
 import httpx
 
-proxies = {"all": "http://127.0.0.1:8080/"}
+ssl_context = httpx.SSLContext()
+ssl_context.load_verify_locations("/path/to/client.pem")
 
-with httpx.Client(proxies=proxies, verify="/path/to/client.pem") as client:
+with httpx.Client(proxy="http://127.0.0.1:8080/", ssl_context=ssl_context) as client:
     response = client.get("https://example.org")
     print(response.status_code)  # should print 200
 ```

.github/workflows/publish.yml

@@ -17,7 +17,7 @@ jobs:
       - uses: "actions/checkout@v4"
       - uses: "actions/setup-python@v5"
         with:
-          python-version: 3.8
+          python-version: 3.9
       - name: "Install dependencies"
         run: "scripts/install"
       - name: "Build package & docs"

.github/workflows/test-suite.yml

@@ -5,7 +5,7 @@ on:
   push:
     branches: ["master"]
   pull_request:
-    branches: ["master"]
+    branches: ["master", "version-*"]
 
 jobs:
   tests:
@@ -14,7 +14,7 @@ jobs:
 
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
 
     steps:
       - uses: "actions/checkout@v4"

CHANGELOG.md

@@ -4,6 +4,44 @@ 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/).
 
+## [UNRELEASED]
+
+### Removed
+
+* Drop support for Python 3.8
+
+## 0.28.1 (6th December, 2024)
+
+* Fix SSL case where `verify=False` together with client side certificates.
+ 
+## 0.28.0 (28th November, 2024)
+
+Be aware that the default *JSON request bodies now use a more compact representation*. This is generally considered a prefered style, tho may require updates to test suites.
+
+The 0.28 release includes a limited set of deprecations...
+
+**Deprecations**:
+
+We are working towards a simplified SSL configuration API.
+
+*For users of the standard `verify=True` or `verify=False` cases, or `verify=<ssl_context>` case this should require no changes. The following cases have been deprecated...*
+
+* The `verify` argument as a string argument is now deprecated and will raise warnings.
+* The `cert` argument is now deprecated and will raise warnings.
+
+Our revised [SSL documentation](docs/advanced/ssl.md) covers how to implement the same behaviour with a more constrained API.
+
+**The following changes are also included**:
+
+* The deprecated `proxies` argument has now been removed.
+* The deprecated `app` argument has now been removed.
+* JSON request bodies use a compact representation. (#3363)
+* Review URL percent escape sets, based on WHATWG spec. (#3371, #3373)
+* Ensure `certifi` and `httpcore` are only imported if required. (#3377)
+* Treat `socks5h` as a valid proxy scheme. (#3178)
+* Cleanup `Request()` method signature in line with `client.request()` and `httpx.request()`. (#3378)
+* Bugfix: When passing `params={}`, always strictly update rather than merge with an existing querystring. (#3364)
+
 ## 0.27.2 (27th August, 2024)
 
 ### Fixed
@@ -590,7 +628,7 @@ See pull requests #1057, #1058.
 
 * Added dedicated exception class `httpx.HTTPStatusError` for `.raise_for_status()` exceptions. (Pull #1072)
 * Added `httpx.create_ssl_context()` helper function. (Pull #996)
-* Support for proxy exlcusions like `proxies={"https://www.example.com": None}`. (Pull #1099)
+* Support for proxy exclusions like `proxies={"https://www.example.com": None}`. (Pull #1099)
 * Support `QueryParams(None)` and `client.params = None`. (Pull #1060)
 
 ### Changed
@@ -818,7 +856,7 @@ We believe the API is now pretty much stable, and are aiming for a 1.0 release s
 
 ### Fixed
 
-- Fix issue with concurrent connection acquiry. (Pull #700)
+- Fix issue with concurrent connection acquisition. (Pull #700)
 - Fix write error on closing HTTP/2 connections. (Pull #699)
 
 ## 0.10.0 (December 29th, 2019)
@@ -1067,7 +1105,7 @@ importing modules within the package.
 
 ## 0.6.7 (July 8, 2019)
 
-- Check for connection aliveness on re-acquiry (Pull #111)
+- Check for connection aliveness on re-acquisition (Pull #111)
 
 ## 0.6.6 (July 3, 2019)
 

README.md

@@ -13,16 +13,14 @@
 </a>
 </p>
 
-HTTPX is a fully featured HTTP client library for Python 3. It includes **an integrated
-command line client**, has support for both **HTTP/1.1 and HTTP/2**, and provides both **sync
-and async APIs**.
+HTTPX is a fully featured HTTP client library for Python 3. It includes **an integrated command line client**, has support for both **HTTP/1.1 and HTTP/2**, and provides both **sync and async APIs**.
 
 ---
 
 Install HTTPX using pip:
 
 ```shell
-pip install httpx
+$ pip install httpx
 ```
 
 Now, let's get started:
@@ -43,7 +41,7 @@ Now, let's get started:
 Or, using the command-line client.
 
 ```shell
-pip install 'httpx[cli]'  # The command line client is an optional dependency.
+$ pip install 'httpx[cli]'  # The command line client is an optional dependency.
 ```
 
 Which now allows us to use HTTPX directly from the command-line...
@@ -94,16 +92,16 @@ Plus all the standard features of `requests`...
 Install with pip:
 
 ```shell
-pip install httpx
+$ pip install httpx
 ```
 
 Or, to include the optional HTTP/2 support, use:
 
 ```shell
-pip install httpx[http2]
+$ pip install httpx[http2]
 ```
 
-HTTPX requires Python 3.8+.
+HTTPX requires Python 3.9+.
 
 ## Documentation
 

docs/advanced/clients.md

@@ -270,8 +270,9 @@ multipart file encoding is available by passing a dictionary with the
 name of the payloads as keys and either tuple of elements or a file-like object or a string as values.
 
 ```pycon
->>> files = {'upload-file': ('report.xls', open('report.xls', 'rb'), 'application/vnd.ms-excel')}
->>> r = httpx.post("https://httpbin.org/post", files=files)
+>>> with open('report.xls', 'rb') as report_file:
+...     files = {'upload-file': ('report.xls', report_file, 'application/vnd.ms-excel')}
+...     r = httpx.post("https://httpbin.org/post", files=files)
 >>> print(r.text)
 {
   ...
@@ -318,7 +319,10 @@ To do that, pass a list of `(field, <file>)` items instead of a dictionary, allo
 For instance this request sends 2 files, `foo.png` and `bar.png` in one request on the `images` form field:
 
 ```pycon
->>> files = [('images', ('foo.png', open('foo.png', 'rb'), 'image/png')),
-                      ('images', ('bar.png', open('bar.png', 'rb'), 'image/png'))]
->>> r = httpx.post("https://httpbin.org/post", files=files)
+>>> with open('foo.png', 'rb') as foo_file, open('bar.png', 'rb') as bar_file:
+...     files = [
+...         ('images', ('foo.png', foo_file, 'image/png')),
+...         ('images', ('bar.png', bar_file, 'image/png')),
+...     ]
+...     r = httpx.post("https://httpbin.org/post", files=files)
 ```

docs/advanced/proxies.md

@@ -73,7 +73,7 @@ This is an optional feature that requires an additional third-party library be i
 You can install SOCKS support using `pip`:
 
 ```shell
-pip install httpx[socks]
+$ pip install httpx[socks]
 ```
 
 You can now configure a client to make requests via a proxy using the SOCKS protocol:

docs/advanced/ssl.md

@@ -1,100 +1,89 @@
 When making a request over HTTPS, HTTPX needs to verify the identity of the requested host. To do this, it uses a bundle of SSL certificates (a.k.a. CA bundle) delivered by a trusted certificate authority (CA).
 
-## Changing the verification defaults
+### Enabling and disabling verification
 
-By default, HTTPX uses the CA bundle provided by [Certifi](https://pypi.org/project/certifi/). This is what you want in most cases, even though some advanced situations may require you to use a different set of certificates.
+By default httpx will verify HTTPS connections, and raise an error for invalid SSL cases...
 
-If you'd like to use a custom CA bundle, you can use the `verify` parameter.
-
-```python
-import httpx
-
-r = httpx.get("https://example.org", verify="path/to/client.pem")
+```pycon
+>>> httpx.get("https://expired.badssl.com/")
+httpx.ConnectError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: certificate has expired (_ssl.c:997)
 ```
 
-Alternatively, you can pass a standard library `ssl.SSLContext`.
+You can disable SSL verification completely and allow insecure requests...
 
 ```pycon
->>> import ssl
->>> import httpx
->>> context = ssl.create_default_context()
->>> context.load_verify_locations(cafile="/tmp/client.pem")
->>> httpx.get('https://example.org', verify=context)
+>>> httpx.get("https://expired.badssl.com/", verify=False)
 <Response [200 OK]>
 ```
 
-We also include a helper function for creating properly configured `SSLContext` instances.
+### Configuring client instances
 
-```pycon
->>> context = httpx.create_ssl_context()
-```
-
-The `create_ssl_context` function accepts the same set of SSL configuration arguments
-(`trust_env`, `verify`, `cert` and `http2` arguments)
-as `httpx.Client` or `httpx.AsyncClient`
+If you're using a `Client()` instance you should pass any `verify=<...>` configuration when instantiating the client.
 
-```pycon
->>> import httpx
->>> context = httpx.create_ssl_context(verify="/tmp/client.pem")
->>> httpx.get('https://example.org', verify=context)
-<Response [200 OK]>
-```
+By default the [certifi CA bundle](https://certifiio.readthedocs.io/en/latest/) is used for SSL verification.
 
-Or you can also disable the SSL verification entirely, which is _not_ recommended.
+For more complex configurations you can pass an [SSL Context](https://docs.python.org/3/library/ssl.html) instance...
 
 ```python
+import certifi
 import httpx
+import ssl
 
-r = httpx.get("https://example.org", verify=False)
+# This SSL context is equivelent to the default `verify=True`.
+ctx = ssl.create_default_context(cafile=certifi.where())
+client = httpx.Client(verify=ctx)
 ```
 
-## SSL configuration on client instances
-
-If you're using a `Client()` instance, then you should pass any SSL settings when instantiating the client.
+Using [the `truststore` package](https://truststore.readthedocs.io/) to support system certificate stores...
 
 ```python
-client = httpx.Client(verify=False)
-```
-
-The `client.get(...)` method and other request methods *do not* support changing the SSL settings on a per-request basis. If you need different SSL settings in different cases you should use more that one client instance, with different settings on each. Each client will then be using an isolated connection pool with a specific fixed SSL configuration on all connections within that pool.
+import ssl
+import truststore
+import httpx
 
-## Client Side Certificates
+# Use system certificate stores.
+ctx = truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+client = httpx.Client(verify=ctx)
+```
 
-You can also specify a local cert to use as a client-side certificate, either a path to an SSL certificate file, or two-tuple of (certificate file, key file), or a three-tuple of (certificate file, key file, password)
+Loding an alternative certificate verification store using [the standard SSL context API](https://docs.python.org/3/library/ssl.html)...
 
 ```python
-cert = "path/to/client.pem"
-client = httpx.Client(cert=cert)
-response = client.get("https://example.org")
+import httpx
+import ssl
+
+# Use an explicitly configured certificate store.
+ctx = ssl.create_default_context(cafile="path/to/certs.pem")  # Either cafile or capath.
+client = httpx.Client(verify=ctx)
 ```
 
-Alternatively...
+### Client side certificates
 
-```python
-cert = ("path/to/client.pem", "path/to/client.key")
-client = httpx.Client(cert=cert)
-response = client.get("https://example.org")
-```
+Client side certificates allow a remote server to verify the client. They tend to be used within private organizations to authenticate requests to remote servers.
 
-Or...
+You can specify client-side certificates, using the [`.load_cert_chain()`](https://docs.python.org/3/library/ssl.html#ssl.SSLContext.load_cert_chain) API...
 
 ```python
-cert = ("path/to/client.pem", "path/to/client.key", "password")
-client = httpx.Client(cert=cert)
-response = client.get("https://example.org")
+ctx = ssl.create_default_context()
+ctx.load_cert_chain(certfile="path/to/client.pem")  # Optionally also keyfile or password.
+client = httpx.Client(verify=ctx)
 ```
 
-## Making HTTPS requests to a local server
+### Working with `SSL_CERT_FILE` and `SSL_CERT_DIR`
+
+`httpx` does respect the `SSL_CERT_FILE` and `SSL_CERT_DIR` environment variables by default. For details, refer to [the section on the environment variables page](../environment_variables.md#ssl_cert_file).
+
+### Making HTTPS requests to a local server
 
 When making requests to local servers, such as a development server running on `localhost`, you will typically be using unencrypted HTTP connections.
 
-If you do need to make HTTPS connections to a local server, for example to test an HTTPS-only service, you will need to create and use your own certificates. Here's one way to do it:
+If you do need to make HTTPS connections to a local server, for example to test an HTTPS-only service, you will need to create and use your own certificates. Here's one way to do it...
 
 1. Use [trustme](https://github.com/python-trio/trustme) to generate a pair of server key/cert files, and a client cert file.
-1. Pass the server key/cert files when starting your local server. (This depends on the particular web server you're using. For example, [Uvicorn](https://www.uvicorn.org) provides the `--ssl-keyfile` and `--ssl-certfile` options.)
-1. Tell HTTPX to use the certificates stored in `client.pem`:
+2. Pass the server key/cert files when starting your local server. (This depends on the particular web server you're using. For example, [Uvicorn](https://www.uvicorn.org) provides the `--ssl-keyfile` and `--ssl-certfile` options.)
+3. Configure `httpx` to use the certificates stored in `client.pem`.
 
 ```python
-client = httpx.Client(verify="/tmp/client.pem")
-response = client.get("https://localhost:8000")
+ctx = ssl.create_default_context(cafile="client.pem")
+client = httpx.Client(verify=ctx)
 ```

docs/api.md

@@ -159,3 +159,18 @@ what gets sent over the wire.*
 * `def delete(name, [domain], [path])`
 * `def clear([domain], [path])`
 * *Standard mutable mapping interface*
+
+## `Proxy`
+
+*A configuration of the proxy server.*
+
+```pycon
+>>> proxy = Proxy("http://proxy.example.com:8030")
+>>> client = Client(proxy=proxy)
+```
+
+* `def __init__(url, [ssl_context], [auth], [headers])`
+* `.url` - **URL**
+* `.auth` - **tuple[str, str]**
+* `.headers` - **Headers**
+* `.ssl_context` - **SSLContext**

docs/async.md

@@ -23,7 +23,7 @@ To make asynchronous requests, you'll need an `AsyncClient`.
 ```
 
 !!! tip
-    Use [IPython](https://ipython.readthedocs.io/en/stable/) or Python 3.8+ with `python -m asyncio` to try this code interactively, as they support executing `async`/`await` expressions in the console.
+    Use [IPython](https://ipython.readthedocs.io/en/stable/) or Python 3.9+ with `python -m asyncio` to try this code interactively, as they support executing `async`/`await` expressions in the console.
 
 ## API Differences