httpx request兼容性

HTTPX旨在與requests API廣泛兼容，盡管在某些地方存在一些設(shè)計差異。

本文檔概述了 API 的不同之處...

重定向

與 requests不同，HTTPX 在默認情況下不遵循重定向。

我們在這里的行為不同，因為自動重定向可以很容易地掩蓋不必要的網(wǎng)絡(luò)調(diào)用。

您仍然可以啟用行為以自動跟蹤重定向，但您需要明確執(zhí)行此操作...

response = client.get(url, follow_redirects=True)

或者實例化客戶端，默認情況下啟用重定向跟隨...

client = httpx.Client(follow_redirects=True)

客戶端實例

?requests.Session?的 HTTPX 等效值為? httpx.Client?。

session = requests.Session(**kwargs)

通常等效于

client = httpx.Client(**kwargs)

請求網(wǎng)址

?response.url?將返回一個URL實例，而不是一個字符串。

如果需要字符串實例，請使用?str(response.url)?。

確定下一個重定向請求

?requests?庫公開了一個?response.next?屬性，可用于獲取下一個重定向請求。

session = requests.Session()
request = requests.Request("GET", ...).prepare()
while request is not None:
    response = session.send(request, allow_redirects=False)
    request = response.next

在 HTTPX 中，此屬性改為命名為?response.next_request? 。例如：

client = httpx.Client()
request = client.build_request("GET", ...)
while request is not None:
    response = client.send(request)
    request = response.next_request

請求內(nèi)容

對于上傳原始文本或二進制內(nèi)容，我們更喜歡使用?content?參數(shù)，以便更好地將這種用法與上傳表單數(shù)據(jù)的情況分開。

例如，?content=...?用于上傳原始內(nèi)容：

# Uploading text, bytes, or a bytes iterator.
httpx.post(..., content=b"Hello, world")

和? data=...?用于發(fā)送表單數(shù)據(jù)：

# Uploading form data.
httpx.post(..., data={"message": "Hello, world"})

使用? data=<text/byte content>?將引發(fā)棄用警告，并且預(yù)計在 HTTPX 1.0 版本中將完全刪除。

上傳文件

HTTPX 嚴格強制要求上載文件必須以二進制模式打開，以避免因嘗試上載以文本模式打開的文件而導(dǎo)致的字符編碼問題。

內(nèi)容編碼

HTTPX使用?utf-8?編碼?str?請求體。例如，當(dāng)使用?content=<str>?時，請求正文將在通過線路發(fā)送之前編碼為?utf-8?。這與使用?latin1?的請求不同。如果需要顯式編碼，請顯式傳遞編碼的字節(jié)，例如?content=<str>.encode("latin1")?。對于響應(yīng)體，假設(shè)服務(wù)器沒有發(fā)送顯式編碼，那么HTTPX將盡最大努力找出合適的編碼。HTTPX使用?charset_normalizer?猜測用于解碼響應(yīng)的編碼?；赝说侥莻€位置，或者任何少于32個八位字節(jié)的內(nèi)容都將使用?utf-8?和?error="replace"?解碼器策略進行解碼。

Cookies

如果使用client實例，則應(yīng)始終在client上設(shè)置 Cookie，而不是按請求設(shè)置。

支持以下用法：

client = httpx.Client(cookies=...)
client.post(...)

不支持以下用法：

client = httpx.Client()
client.post(..., cookies=...)

我們更喜歡在這里強制實施更嚴格的 API，因為它提供了對 cookie 持久性的更清晰的期望，尤其是在發(fā)生重定向時。

狀態(tài)代碼

在我們的文檔中，我們更喜歡大寫版本，例如 ?codes.NOT_FOUND?，但也提供小寫版本，以便與?requests API ?兼容。

請求包括 HTTPX 不支持的狀態(tài)代碼的各種同義詞。

流式處理響應(yīng)

HTTPX 提供了一個?.stream()?接口，而不是使用?stream=True? 。這可確保流式處理響應(yīng)始終在流塊外部正確關(guān)閉，并使其在視覺上更清晰，流式處理 I/O API 可在哪些點與響應(yīng)一起使用。

例如：

with httpx.stream("GET", "https://www.example.com") as response:
    ...

在?stream()?塊請求中，數(shù)據(jù)通過以下方式提供：

• ?.iter_bytes()?- 而不是?response.iter_content()?
• ?.iter_text()?- 而不是?response.iter_content(decode_unicode=True)?
• ?.iter_lines()?- 對應(yīng)于?response.iter_lines()?
• ?.iter_raw()?- 用這個代替?response.raw?
• ?.read()?- 閱讀整個響應(yīng)正文，制作?request.text?和?response.content?可用。

代理密鑰

當(dāng)?httpx.Client(proxies={...})?用于映射到選定的不同代理時，我們使用完整的URL方案，例如?proxies={"http://": ..., "https://": ...}?。

這與?requestsproxies={"http": ..., "https": ...}? 的用法不同。

此更改是為了更好地與更復(fù)雜的映射保持一致，其中可能還包括域名，例如?proxies={"all://": ..., "all://www.example.com": None}?為將所有請求映射到代理，但對“www.example.com”的請求除外，這些請求具有顯式排除。

另請注意，?requests.Session.request(...)?允許?proxies=...?參數(shù)，而不允許?httpx.Client.request(...)?。

SSL 配置

使用?Client?實例時，?trust_env?、?verify ?和?cert?參數(shù)應(yīng)始終在客戶端實例化時傳遞，而不是傳遞給請求方法。

如果需要多個不同的 SSL 配置，則應(yīng)為每個 SSL 配置使用不同的客戶端實例。

Request支持?REQUESTS_CA_BUNDLE?指向文件或目錄的請求。HTTPX支持?SSL_CERT_FILE?（對于文件）和?SSL_CERT_DIR?（對于目錄）OpenSSL變量。

HTTP 方法上的請求正文

HTTP 的?GET?、?DELETE?、?HEAD ?和?OPTIONS?方法被指定為不支持請求正文。為了與此保持一致，?.get?、?.delete ?、?.head?和?.options ?函數(shù)不支持?content?、 ?files?、 ?data?或?json?參數(shù)。

如果您確實需要使用這些 http 方法發(fā)送請求數(shù)據(jù)，則應(yīng)改用.request泛型函數(shù)。

httpx.request(
  method="DELETE",
  url="https://www.example.com/",
  content=b'A request body on a DELETE request.'
)

檢查成功和失敗響應(yīng)

我們不支持?response.is_ok?，因為那里的命名是模棱兩可的，并且可能錯誤地暗示等同于?response.status_code == codes.OK? .相反，我們提供?response.is_success?屬性，該屬性可用于檢查 ?2xx ?響應(yīng)。

請求實例化

在 HTTPX 中沒有預(yù)準(zhǔn)備請求的概念。如果您需要自定義請求實例化，請參見請求實例。

此外，httpx.Request()不支持auth 、timeout 、follow_redirects 、proxies、verify和cert參數(shù)。但是，這些在httpx.request 、httpx.get、httpx.post 等 以及 Client 實例中可用。

模擬

如果您需要模擬 HTTPX，就像?requests?對?responses?和?requests-mock?測試實用程序一樣，請參閱 RESPX。

網(wǎng)絡(luò)層

requests將大部分 HTTP 網(wǎng)絡(luò)代碼推遲到優(yōu)秀的 urllib3 庫。

另一方面，HTTPX使用HTTPCore作為其核心HTTP網(wǎng)絡(luò)層，這與urllib3不同。

查詢參數(shù)

?requests ?忽略值為 ?None ?的?params?（例如 ?requests.get(..., params={"foo": None})?）。 HTTPX 不支持此功能

事件掛接

?requests ?允許事件掛鉤改變 ?Request ?和 ?Response ?對象。有關(guān)?request?的相關(guān)內(nèi)容，請參閱文檔中給出的示例。

在 HTTPX 中，事件掛鉤可以訪問請求和響應(yīng)的屬性，但事件掛鉤回調(diào)不能改變原始請求/響應(yīng)。

如果您正在尋找更多控制，請考慮查看自定義傳輸。