urllib3

urllib3 的文檔
urllib3 是 python 的 HTTP 客戶端，它提供了很多 python 標準庫中沒有的關鍵特性：線程安全、連接池、客戶端 SSL/TLS 驗證、用分段編碼上傳文件、重試請求和處理HTTP重定向的助手、支持gzip和deflate編碼、HTTP和SOCKS的代理支持、100％的測試覆蓋率。

1.用戶指南

1.1 發出請求

import urllib3 # 先實例化PoolManager的對象，該對象能自動處理線程安全和連接池的細節 http = urllib3.PoolManager() # 用 request() 發請求 r = http.request('GET', 'http://httpbin.org/robots.txt')

‘GET’ 可替換成其它的 HTTP 請求。

1.2 響應內容

request() 方法返回 HTTPResponse 對象，該對象有 status、data、headers 等屬性。
status：響應的狀態碼；
headers：HTTP的請求頭，是 HTTPHeaderDict 對象；
data：響應的內容，bytes 對象。data 是 JSON 內容時能通過解碼和反序列化來加載。

1.3 請求數據

請求頭

能以字典的形式在 request() 的 headers 參數中指定請求頭。

查詢的參數

對于 GET、HEAD、DELETE 請求，能把參數以字典的格式放到 fields 參數里傳給 request()。

r = http.request('GET', 'http://httpbin.org/get', fields={'key1': 'value1', 'key2': 'value2'})

而 POST 和 PUT 請求需要把參數手動編碼到 url 上。

from urllib.parse import urlencode encoded_arg = urlencode({'key1': 'value1', 'key2': 'value2'}) url = url + '?' + encoded_arg r = http.request('POST', url)

urlencode 函數也能接收雙元素元組的序列：

encoded_arg = urlencode([('key1', 'value1'), ('key2', 'value2')])

表單數據

POST 和 PUT 請求中，放在 fields 中的參數會被 urllib3 自動編碼為表單格式。

JSON

發送 JSON 請求要通過 body 參數指定 JSON 數據，并設置請求頭中的 Content-Type 項。

import json data = {'key': 'value'} encoded_data = json.dumps(data).encode('utf-8') r = http.request('POST', url, body=encoded_data, headers={'Content-Type': 'application/json'})

文件和二進制數據

上傳文件把 fields 中的文件字段設置為形如 (文件名，數據) 的元組。

with open('test.txt') as f:file_data = f.read() r = http.request('POST', url,fields = {'filefield': ('test.txt', file_data),})

指定文件名不是必須的，能用來匹配瀏覽器的行為。也能在元組中傳遞第三項來顯示指定文件的 MIME¹ 類型：(文件名，數據，MIME類型)。
用 body 參數能直接傳輸二進制數據，Content-Type 最好同時改一下。

1.4 證書驗證

1.25 版本后的 urllib3 會在默認情況下驗證 HTTPS 連接 (cert_reqs = ‘CERT_REQUIRED’)。
除非另外指定，否則 urllib3 會自動加載默認的系統證書庫。最可靠的跨平臺方式是使用能提供 Mozilla 根證書捆綁的 certifi 模塊。
使用 pip 直接安裝或者用 urllib3 的額外命令 secure 安裝。
獲得證書后，您可以創建一個在發出請求時驗證證書的 PoolManager。

import certifi http = urllib3.PoolManager(cert_reqs='CERT_REQUIRED',ca_certs=certifi.where())

PoolManager 會自動處理證書驗證，驗證失敗時會拋出 SSLError。

1.5 使用超時參數

使用超時參數能控制請求中止前允許運行的最大時長。

r = http.request('GET', url, timeout=2.5)

使用一個 Timeout 實例能進行更細的控制：連接和讀取分別設置時長。

r = http.request('GET', url, timeout=urllib3.Timeout(connect=1.0, read=2.0))

可以在創建池的時候指定超時，使所有的請求都是相同的超時。該設置 會被 request() 中的超時設置所覆蓋。

http = urllib3.PoolManager(timeout=3.0)

1.6 重試請求

默認情況下，urllib3將重試請求3次，并最多進行3次重定向。能通過 retries 參數來控制重試請求。

r = http.request('GET', url, retries=10)

retries 設置為 False 時，禁用所有重試和重定向請求。要禁用重定向但保留重試邏輯，設置 redirect 為 False。使用 Retry 實例能進行更精細的控制。
在創建池的時候指定重試，會為所有請求都配置該策略。

2. 高級用法

2.1 自定義池行為

PoolManager 類會根據需要自動為每個主機創建 ConnectionPool 實例。默認情況下最多創建 10 個實例。如果想請求很多不同的主機，增加該數值有助于提高性能。

http = urllib3.PoolManager(num_pools=50)

這么做同時也會增加內存和套接字的花銷。
與上述情況類似。ConnectionPool 類還保留了一個獨立的 HTTPConnection 實例池。其中的連接在一個獨立請求期間使用，請求完成后又會返回池內。這種可復用的連接默認只有一個。如果想同時對相同的主機做很多請求的話，增加該數值有助于提高性能(下面兩句代碼等效²，選用一句即可)。

# 二者選其一 http = urllib3.PoolManager(maxszie=10) http = urllib3.HTTPConnectionPool('baidu.com', maxsize=10)

ConnectionPool 類的池行為和 PoolManager 類不同。默認情況下，創建新請求時如果池內沒有空閑的連接，就會新建一個連接。但是該連接在池內連接數已大于最大值的時候不會保留下來。也就是說，maxsize 參數不是可以向某個主機打開的最大連接數，而是池內可保留的最大連接數。指定參數 block=True 時，允許打開的最大連接數就是 maxsize 設定的數值。

# 二者選其一 http = urllib3.PoolManager(maxsize=10, block=True) http = urllib3.HTTPConnectionPool(maxsize=10, block=True)

新請求會被阻塞，直到池中有連接可用為止。在多線程的應用中，這樣做能避免太多連接使主機內存溢出。

2.2 流和IO

處理大的響應時，最好使用流式傳輸。

http = urllib3.PoolManager() r = http.request('GET','http://httpbin.org/bytes/1024',preload_content=False) for chunk in r.stream(32):print(chunk) r.release_conn()

把 preload_content 設為 False 時，urllib3 會流失傳輸響應內容。stream 函數使你能遍歷響應內容的大塊。必須用 release_conn() 函數把 http 連接釋放回連接池，該連接才能復用。
流式傳輸獲得的 HTPResponse 對象能看做是一個文件對象，允許進行緩沖。能使用 read()函數，還能用 codecs 模塊對內容進行解碼。

2.3 代理

使用 ProxyManager³ 能通過 HTTP 代理發送請求。

proxy = urllib3.ProxyManager('http://host:port/') proxy.request('GET', url)

通過 SOCKSProxyManager 能連接到 SOCKS4 和 SOCKS5 的代理。使用 SOCKS 代理需要安裝 PySocks 或者安裝 urllib3 時帶上額外的 socks 模塊。

2.4 自定義SSL證書

不用使用 certifi 就能提供自己的證書捆綁包。當你已經生成自己的證書或者使用私有證書機構時，這非常有用。只要在創建 PoolManager 時提供到證書捆綁包的完整路徑就行。

http = urllib3.PoolManager(cert_request='CERT_REQUIRED', ca_certs='path/bundle')

使用自己的證書捆綁包時，只有能用該證書驗證的請求才能成功。對于不需要自定義證書驗證的 URL，最好有一個單獨的 PoolManager 用來發出請求。

2.5 客戶端證書

指定客戶端證書可用于服務端和客戶端驗證彼此的身份。通常這些證書是從同一個證書機構頒發的。

http = urllib3.PoolManager(cert_file='/path/client_cert.pem',cert_reqs='CERT_REQUIRED',ca_certs='/path/certificate_bundle')

如果您具有加密的客戶端證書私鑰，則可以使用key_password參數指定用于解密密鑰的密碼。

http = urllib3.PoolManager(cert_file='/path/client_cert.pem',cert_reqs='CERT_REQUIRED',key_file='/path/client.key',key_password='password')

2.6 證書驗證和Mac OS 系統

蘋果提供的 Python 和 OpenSSL 庫包含一個修補程序，讓它們能自動檢查系統鑰匙串的證書。如果您指定自定義證書并且看到請求意外成功，這可能會令人驚訝。例如，如果您要指定自己的證書進行驗證，并且服務器提供了不同的證書，則您以為連接會失敗。但是，如果該服務器出示系統鑰匙串中的證書，則連接將成功。

2.7 SSL警告

urllib3 會基于證書驗證支持的級別發出幾個不同的警告。這些警告表明特殊情況的出現，能用不同的方式解決。
InsecureRequestWarning：對 HTTPS URL 發出請求時沒有用證書驗證。
InsecurePlatformWarning：在有過期 ssl 模塊的Python 2平臺上會發生。這些舊的 ssl 模塊可能導致一些不安全的請求在該失敗的地方成功，而安全的請求在該成功的地方失敗。
SNIMissingWarning：2.7.9之前的Python 2版本上會出現。這些版本缺少 SNI 支持，可能會導致服務器出示客戶端認為無效的證書。
不建議進行未經驗證的 HTTPS 請求。如果了解風險并想忽視這些警告要使用 disable_warnings()。

urllib3.disable_warnings()

此外，還能用標準庫的 logging 模塊捕獲這些警告；可以通過設置PYTHONWARNINGS 環境變量或使用 -W 標志在解釋器級別抑制警告 。

---

多用途互聯網郵件擴展類型。使 HTTP 傳輸的數據更加豐富。斜杠前是數據的大類型如文本、聲音、圖像等，斜杠后面是具體的文件類型。Headers 中的 Content-Type 指定的就是 MIME 類型。 ??

PoolManager 是 urllib3.request.RequestMethods 的子類；HTTPConnectionPool 同時是 ConnectionPool 和 urllib3.request.RequestMethods 的子類。所以，它們的對象都能發出請求。 ??

ProxyManager 是 PoolManager 的子類。 ??

總結

以上是生活随笔為你收集整理的python-urllib3的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。