httpx request兼容性

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

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

重定向

與 requests不同，HTTPX 在默認(rèn)情況下不遵循重定向。

我們?cè)谶@里的行為不同，因?yàn)樽詣?dòng)重定向可以很容易地掩蓋不必要的網(wǎng)絡(luò)調(diào)用。

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

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

或者實(shí)例化客戶端，默認(rèn)情況下啟用重定向跟隨...

client = httpx.Client(follow_redirects=True)

客戶端實(shí)例

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

session = requests.Session(**kwargs)

通常等效于

client = httpx.Client(**kwargs)

請(qǐng)求網(wǎng)址

?response.url?將返回一個(gè)URL實(shí)例，而不是一個(gè)字符串。

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

確定下一個(gè)重定向請(qǐng)求

?requests?庫(kù)公開了一個(gè)?response.next?屬性，可用于獲取下一個(gè)重定向請(qǐng)求。

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

請(qǐng)求內(nèi)容

對(duì)于上傳原始文本或二進(jìn)制內(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ù)計(jì)在 HTTPX 1.0 版本中將完全刪除。

上傳文件

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

內(nèi)容編碼

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

Cookies

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

支持以下用法：

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

不支持以下用法：

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

我們更喜歡在這里強(qiáng)制實(shí)施更嚴(yán)格的 API，因?yàn)樗峁┝藢?duì) cookie 持久性的更清晰的期望，尤其是在發(fā)生重定向時(shí)。

狀態(tài)代碼

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

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

流式處理響應(yīng)

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

例如：

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

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

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

代理密鑰

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

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

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

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

SSL 配置

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

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

Request支持?REQUESTS_CA_BUNDLE?指向文件或目錄的請(qǐng)求。HTTPX支持?SSL_CERT_FILE?（對(duì)于文件）和?SSL_CERT_DIR?（對(duì)于目錄）OpenSSL變量。

HTTP 方法上的請(qǐng)求正文

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

如果您確實(shí)需要使用這些 http 方法發(fā)送請(qǐng)求數(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?，因?yàn)槟抢锏拿悄＠鈨煽傻模⑶铱赡苠e(cuò)誤地暗示等同于?response.status_code == codes.OK? .相反，我們提供?response.is_success?屬性，該屬性可用于檢查 ?2xx ?響應(yīng)。

請(qǐng)求實(shí)例化

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

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

模擬

如果您需要模擬 HTTPX，就像?requests?對(duì)?responses?和?requests-mock?測(cè)試實(shí)用程序一樣，請(qǐng)參閱 RESPX。

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

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

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

查詢參數(shù)

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

事件掛接

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

在 HTTPX 中，事件掛鉤可以訪問(wèn)請(qǐng)求和響應(yīng)的屬性，但事件掛鉤回調(diào)不能改變?cè)颊?qǐng)求/響應(yīng)。

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