Request 對象?

以下方法介紹了 Request 的公開接口，因此子類可以覆蓋所有這些方法。這里還定義了幾個公開屬性，客戶端可以利用這些屬性了解經(jīng)過解析的請求。

Request.full_url?

傳給構(gòu)造函數(shù)的原始 URL。

在 3.4 版更改.

Request.full_url 是一個帶有 setter、getter 和 deleter 的屬性。讀取 full_url 屬性將會返回附帶片段（fragment）的初始請求 URL。

Request.type?

URI 方式。

Request.host?

URI 權(quán)限，通常是整個主機，但也有可能帶有冒號分隔的端口號。

Request.origin_req_host?

請求的原始主機，不含端口。

Request.selector?

URI 路徑。若 Request 使用代理，selector 將會是傳給代理的完整 URL。

Request.data?

請求的數(shù)據(jù)體，未給出則為 None 。

在 3.4 版更改: 現(xiàn)在如果修改 Request.data 的值，則會刪除之前設置或計算過的“Content-Length”頭部信息。

Request.unverifiable?

布爾值，標識本請求是否屬于 RFC 2965 中定義的無法驗證的情況。

Request.method?

要采用的 HTTP 請求方法。默認為 None，表示 get_method() 將對方法進行正常處理。設置本值可以覆蓋 get_method() 中的默認處理過程，設置方式可以是在 Request 的子類中給出默認值，也可以通過 method 參數(shù)給 Request 構(gòu)造函數(shù)傳入一個值。

3.3 新版功能.

在 3.4 版更改: 現(xiàn)在可以在子類中設置默認值；而之前只能通過構(gòu)造函數(shù)的實參進行設置。

Request.get_method()?

返回表示 HTTP 請求方法的字符串。如果 Request.method 不為 None ，則返回其值。否則若 Request.data 為 則返回 'GET'，不為 None 則返回 'POST' 。只對 HTTP 請求有效。

在 3.3 版更改: 現(xiàn)在 get_method 會兼顧 Request.method 的值。

Request.add_header(key, val)?

Add another header to the request. Headers are currently ignored by all handlers except HTTP handlers, where they are added to the list of headers sent to the server. Note that there cannot be more than one header with the same name, and later calls will overwrite previous calls in case the key collides. Currently, this is no loss of HTTP functionality, since all headers which have meaning when used more than once have a (header-specific) way of gaining the same functionality using only one header. Note that headers added using this method are also added to redirected requests.

Request.add_unredirected_header(key, header)?

添加一項不會被加入重定向請求的頭部信息。

Request.has_header(header)?

返回本實例是否帶有命名頭部信息（對常規(guī)數(shù)據(jù)和非重定向數(shù)據(jù)都會檢測）。

Request.remove_header(header)?

從本請求實例中移除指定命名的頭部信息（對常規(guī)數(shù)據(jù)和非重定向數(shù)據(jù)都會檢測）。

3.4 新版功能.

Request.get_full_url()?

返回構(gòu)造器中給定的 URL。

在 3.4 版更改.

返回 Request.full_url

Request.set_proxy(host, type)?

連接代理服務器，為當前請求做準備。 host 和 type 將會取代本實例中的對應值，selector 將會是構(gòu)造函數(shù)中給出的初始 URL。

Request.get_header(header_name, default=None)?

返回給定頭部信息的數(shù)據(jù)。如果該頭部信息不存在，返回默認值。

Request.header_items()?

返回頭部信息，形式為（名稱, 數(shù)據(jù)）的元組列表。

OpenerDirector 對象?

OpenerDirector 實例有以下方法：

OpenerDirector.add_handler(handler)?

handler 應為 BaseHandler 的實例。將檢索以下類型的方法，并將其添加到對應的處理鏈中（注意 HTTP 錯誤是特殊情況）。請注意，下文中的 protocol 應替換為要處理的實際協(xié)議，例如 http_response() 將是 HTTP 協(xié)議響應處理函數(shù)。并且 type 也應替換為實際的 HTTP 代碼，例如 http_error_404() 將處理 HTTP 404 錯誤。

• <protocol>_open() — 表明該 handler 知道如何打開 protocol 協(xié)議的URL。

  更多信息請參閱 BaseHandler.<protocol>_open() 。

• http_error_<type>() — 表明該 handler 知道如何處理代碼為 type 的 HTTP 錯誤。

  更多信息請參閱 BaseHandler.http_error_<nnn>() 。

• <protocol>_error() — 表明該 handler 知道如何處理來自協(xié)議為 protocol （非http）的錯誤。

• <protocol>_request() — 表明該 handler 知道如何預處理協(xié)議為 protocol 的請求。

  更多信息請參閱 BaseHandler.<protocol>_request() 。

• <protocol>_response() — 表明該 handler 知道如何后處理協(xié)議為 protocol 的響應。

  更多信息請參閱 BaseHandler.<protocol>_response() 。

OpenerDirector.open(url, data=None[, timeout])?

Open the given url (which can be a request object or a string), optionally passing the given data. Arguments, return values and exceptions raised are the same as those of urlopen() (which simply calls the open() method on the currently installed global OpenerDirector). The optional timeout parameter specifies a timeout in seconds for blocking operations like the connection attempt (if not specified, the global default timeout setting will be used). The timeout feature actually works only for HTTP, HTTPS and FTP connections.

OpenerDirector.error(proto, *args)?

處理給定協(xié)議的錯誤。將用給定的參數(shù)（協(xié)議相關(guān)）調(diào)用已注冊的給定協(xié)議的錯誤處理程序。HTTP 協(xié)議是特殊情況，采用 HTTP 響應碼來確定具體的錯誤處理程序；請參考 handler 類的 http_error_<type>() 方法。

返回值和異常均與 urlopen() 相同。

OpenerDirector 對象分 3 個階段打開 URL：

每個階段中調(diào)用這些方法的次序取決于 handler 實例的順序。

1. 每個具有 _request() 這類方法的 handler 都會調(diào)用本方法對請求進行預處理。

2. 調(diào)用具有 _open() 這類方法的 handler 來處理請求。當 handler 返回非None 值（即響應）或引發(fā)異常（通常是 URLError）時，本階段結(jié)束。本階段能夠傳播異常。

   事實上，以上算法首先會嘗試名為 default_open() 的方法。 如果這些方法全都返回 None，則會對名為 <protocol>_open() 的方法重復此算法。 如果這些方法也全都返回 None，則會繼續(xù)對名為 unknown_open() 的方法重復此算法。

   請注意，這些方法的代碼可能會調(diào)用 OpenerDirector 父實例的 open() 和 error() 方法。

3. 每個具有 _response() 這類方法的 handler 都會調(diào)用這些方法，以對響應進行后處理。

BaseHandler 對象?

BaseHandler 對象提供了一些直接可用的方法，以及其他一些可供派生類使用的方法。以下是可供直接使用的方法：

BaseHandler.add_parent(director)?

將 director 加為父 OpenerDirector。

BaseHandler.close()?

移除所有父 OpenerDirector。

以下屬性和方法僅供 BaseHandler 的子類使用：

BaseHandler.parent?

一個可用的 OpenerDirector，可用于以其他協(xié)議打開 URI，或處理錯誤。

BaseHandler.default_open(req)?

本方法在 BaseHandler 中 未 予定義，但其子類若要捕獲所有 URL 則應進行定義。

This method, if implemented, will be called by the parent OpenerDirector. It should return a file-like object as described in the return value of the open() method of OpenerDirector, or None. It should raise URLError, unless a truly exceptional thing happens (for example, MemoryError should not be mapped to URLError).

本方法將會在所有協(xié)議的 open 方法之前被調(diào)用。

BaseHandler.<protocol>_open(req)

本方法在 BaseHandler 中 未 予定義，但其子類若要處理給定協(xié)議的 URL 則應進行定義。

若定義了本方法，將會被父 OpenerDirector 對象調(diào)用。返回值和 default_open() 的一樣。

BaseHandler.unknown_open(req)?

本方法在 BaseHandler 中 未 予定義，但其子類若要捕獲并打開所有未注冊 handler 的 URL，則應進行定義。

若實現(xiàn)了本方法，將會被 parent 屬性指向的父 OpenerDirector 調(diào)用。返回值和 default_open() 的一樣。

BaseHandler.http_error_default(req, fp, code, msg, hdrs)?

本方法在 BaseHandler 中 未 予定義，但其子類若要為所有未定義 handler 的 HTTP 錯誤提供一個兜底方法，則應進行重寫。OpenerDirector 會自動調(diào)用本方法，獲取錯誤信息，而通常在其他時候不應去調(diào)用。

req 會是一個 Request 對象，fp 是一個帶有 HTTP 錯誤體的文件類對象，code 是三位數(shù)的錯誤碼，msg 是供用戶閱讀的解釋信息，hdrs 則是一個包含出錯頭部信息的字典對象。

返回值和觸發(fā)的異常應與 urlopen() 的相同。

BaseHandler.http_error_<nnn>(req, fp, code, msg, hdrs)

nnn 應為三位數(shù)的 HTTP 錯誤碼。本方法在 BaseHandler 中也未予定義，但當子類的實例發(fā)生代碼為 nnn 的 HTTP 錯誤時，若方法存在則會被調(diào)用。

子類應該重寫本方法，以便能處理相應的 HTTP 錯誤。

參數(shù)、返回值和觸發(fā)的異常應與 http_error_default() 相同。

BaseHandler.<protocol>_request(req)

本方法在 BaseHandler 中 未 予定義，但其子類若要對給定協(xié)議的請求進行預處理，則應進行定義。

若實現(xiàn)了本方法，將會被父 OpenerDirector 調(diào)用。req 將為 Request 對象。返回值應為 Request 對象。

BaseHandler.<protocol>_response(req, response)

本方法在 BaseHandler 中 未 予定義，但其子類若要對給定協(xié)議的請求進行后處理，則應進行定義。

若實現(xiàn)了本方法，將會被父 OpenerDirector 調(diào)用。req 將為 Request 對象。response 應實現(xiàn)與 urlopen() 返回值相同的接口。返回值應實現(xiàn)與 urlopen() 返回值相同的接口。

HTTPRedirectHandler 對象?

HTTPRedirectHandler.redirect_request(req, fp, code, msg, hdrs, newurl)?

返回 Request 或 None 對象作為重定向行為的響應。當服務器接收到重定向請求時， http_error_30*() 方法的默認實現(xiàn)代碼將會調(diào)用本方法。如果確實應該發(fā)生重定向，則返回一個新的 Request 對象，使得 http_error_30*() 能重定向至 newurl。否則，若沒有 handler 會處理此 URL，則會引發(fā) HTTPError；或者本方法不能處理但或許會有其他 handler 會處理，則返回 None 。

備注

本方法的默認實現(xiàn)代碼并未嚴格遵循 RFC 2616，即 POST 請求的 301 和 302 響應不得在未經(jīng)用戶確認的情況下自動進行重定向?，F(xiàn)實情況下，瀏覽器確實允許自動重定向這些響應，將 POST 更改為 GET ，于是默認實現(xiàn)代碼就復現(xiàn)了這種處理方式。

HTTPRedirectHandler.http_error_301(req, fp, code, msg, hdrs)?

重定向到 Location: 或 URI: URL。 當?shù)玫?HTTP 'moved permanently' 響應時，本方法會被父級 OpenerDirector 調(diào)用。

HTTPRedirectHandler.http_error_302(req, fp, code, msg, hdrs)?

與 http_error_301() 相同，不過是發(fā)生“found”響應時的調(diào)用。

HTTPRedirectHandler.http_error_303(req, fp, code, msg, hdrs)?

與 http_error_301() 相同，不過是發(fā)生“see other”響應時的調(diào)用。

HTTPRedirectHandler.http_error_307(req, fp, code, msg, hdrs)?

The same as http_error_301(), but called for the 'temporary redirect' response. It does not allow changing the request method from POST to GET.

HTTPRedirectHandler.http_error_308(req, fp, code, msg, hdrs)?

The same as http_error_301(), but called for the 'permanent redirect' response. It does not allow changing the request method from POST to GET.

3.11 新版功能.

HTTPCookieProcessor 對象?

HTTPCookieProcessor 的實例具備一個屬性：

HTTPCookieProcessor.cookiejar?

cookie 存放在 http.cookiejar.CookieJar 中。

ProxyHandler 對象?

ProxyHandler.<protocol>_open(request)

ProxyHandler 將為每種 protocol 準備一個 _open() 方法，在構(gòu)造函數(shù)給出的 proxies 字典中包含對應的代理服務器信息。通過調(diào)用 request.set_proxy()，本方法將把請求轉(zhuǎn)為通過代理服務器，并會調(diào)用 handler 鏈中的下一個 handler 來完成對應的協(xié)議處理。

HTTPPasswordMgr 對象?

以下方法 HTTPPasswordMgr 和 HTTPPasswordMgrWithDefaultRealm 對象均有提供。

HTTPPasswordMgr.add_password(realm, uri, user, passwd)?

uri 可以是單個 URI，也可以是 URI 列表。realm、user 和 passwd 必須是字符串。這使得在為 realm 和超級 URI 進行身份認證時，(user, passwd) 可用作認證令牌。

HTTPPasswordMgr.find_user_password(realm, authuri)?

為給定 realm 和 URI 獲取用戶名和密碼。如果沒有匹配的用戶名和密碼，本方法將會返回 (None, None) 。

對于 HTTPPasswordMgrWithDefaultRealm 對象，如果給定 realm 沒有匹配的用戶名和密碼，將搜索 realm None。

HTTPPasswordMgrWithPriorAuth 對象?

這是 HTTPPasswordMgrWithDefaultRealm 的擴展，以便對那些需要一直發(fā)送認證憑證的 URI 進行跟蹤。

HTTPPasswordMgrWithPriorAuth.add_password(realm, uri, user, passwd, is_authenticated=False)?

realm、uri、user、passwd 的含義與 HTTPPasswordMgr.add_password() 的相同。is_authenticated 為給定 URI 或 URI 列表設置 is_authenticated 標志的初始值。如果 is_authenticated 設為 True ，則會忽略 realm。

HTTPPasswordMgrWithPriorAuth.find_user_password(realm, authuri)?

與 HTTPPasswordMgrWithDefaultRealm 對象的相同。

HTTPPasswordMgrWithPriorAuth.update_authenticated(self, uri, is_authenticated=False)?

更新給定 uri 或 URI 列表的 is_authenticated 標志。

HTTPPasswordMgrWithPriorAuth.is_authenticated(self, authuri)?

返回給定 URI is_authenticated 標志的當前狀態(tài)。

AbstractBasicAuthHandler 對象?

AbstractBasicAuthHandler.http_error_auth_reqed(authreq, host, req, headers)?

通過獲取用戶名和密碼并重新嘗試請求，以處理身份認證請求。 authreq 應該是請求中包含 realm 的頭部信息名稱，host 指定了需要進行身份認證的 URL 和路徑，req 應為 (已失敗的) Request 對象 , headers 應該是出錯的頭部信息。

host 要么是一個認證信息（例如 "python.org" ），要么是一個包含認證信息的 URL（如``"http://python.org/"`` ）。 不論是哪種格式，認證信息中都不能包含用戶信息（因此，"python.org" 和 "python.org:80" 沒問題，而 "joe:password@python.org" 則不行）。

HTTPBasicAuthHandler 對象?

HTTPBasicAuthHandler.http_error_401(req, fp, code, msg, hdrs)?

如果可用的話，請用身份認證信息重試請求。

ProxyBasicAuthHandler 對象?

ProxyBasicAuthHandler.http_error_407(req, fp, code, msg, hdrs)?

如果可用的話，請用身份認證信息重試請求。

AbstractDigestAuthHandler 對象?

AbstractDigestAuthHandler.http_error_auth_reqed(authreq, host, req, headers)?

authreq 應為請求中有關(guān) realm 的頭部信息名稱，host 應為需要進行身份認證的主機，req 應為（已失敗的） Request 對象， headers 則應為出錯的頭部信息。

HTTPDigestAuthHandler 對象?

HTTPDigestAuthHandler.http_error_401(req, fp, code, msg, hdrs)?

如果可用的話，請用身份認證信息重試請求。

ProxyDigestAuthHandler 對象?

ProxyDigestAuthHandler.http_error_407(req, fp, code, msg, hdrs)?

如果可用的話，請用身份認證信息重試請求。

HTTPHandler 對象?

HTTPHandler.http_open(req)?

發(fā)送 HTTP 請求，根據(jù) req.has_data() 的結(jié)果，可能是 GET 或 POST 格式。

HTTPSHandler 對象?

HTTPSHandler.https_open(req)?

發(fā)送 HTTPS 請求，根據(jù) req.has_data() 的結(jié)果，可能是 GET 或 POST 格式。

FileHandler 對象?

FileHandler.file_open(req)?

若無主機名或主機名為 'localhost' ，則打開本地文件。

在 3.2 版更改: 本方法僅適用于本地主機名。如果給出的是遠程主機名，將會觸發(fā) URLError 。

DataHandler 對象?

DataHandler.data_open(req)?

讀取內(nèi)含數(shù)據(jù)的 URL。這種 URL 本身包含了經(jīng)過編碼的數(shù)據(jù)。 RFC 2397 中給出了數(shù)據(jù) URL 的語法定義。目前的代碼庫將忽略經(jīng)過 base64 編碼的數(shù)據(jù) URL 中的空白符，因此 URL 可以放入任何源碼文件中。如果數(shù)據(jù) URL 的 base64 編碼尾部缺少填充，即使某些瀏覽器不介意，但目前的代碼庫仍會引發(fā) ValueError。

FTPHandler 對象?

FTPHandler.ftp_open(req)?

打開由 req 給出的 FTP 文件。登錄時的用戶名和密碼總是為空。

CacheFTPHandler 對象?

CacheFTPHandler 對象即為加入以下方法的 FTPHandler 對象：

CacheFTPHandler.setTimeout(t)?

設置連接超時為 t 秒。

CacheFTPHandler.setMaxConns(m)?

設置已緩存的最大連接數(shù)為 m 。

UnknownHandler 對象?

UnknownHandler.unknown_open()?

觸發(fā) URLError 異常。

HTTPErrorProcessor 對象?

HTTPErrorProcessor.http_response(request, response)?

處理出錯的 HTTP 響應。

對于 200 錯誤碼，響應對象應立即返回。

對于 200 以外的錯誤碼，只通過 OpenerDirector.error() 將任務傳給 handler 的 http_error_<type>() 方法。如果最終沒有 handler 處理錯誤， HTTPDefaultErrorHandler 將觸發(fā) HTTPError。

HTTPErrorProcessor.https_response(request, response)?

HTTPS 出錯響應的處理。

與 http_response() 方法相同。

例子?

如何利用 urllib 包獲取網(wǎng)絡資源 中給出了更多的示例。

以下示例將讀取 python.org 主頁并顯示前 300 個字節(jié)的內(nèi)容：

>>> import urllib.request
>>> with urllib.request.urlopen('http://www.python.org/') as f:
...     print(f.read(300))
...
b'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">\n\n\n<html
xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">\n\n<head>\n
<meta http-equiv="content-type" content="text/html; charset=utf-8" />\n
<title>Python Programming '

請注意，urlopen 將返回字節(jié)對象。這是因為 urlopen 無法自動確定由 HTTP 服務器收到的字節(jié)流的編碼。通常，只要能確定或猜出編碼格式，就應將返回的字節(jié)對象解碼為字符串。

下述 W3C 文檔 https://www.w3.org/International/O-charset列出了可用于指明（X）HTML 或 XML 文檔編碼信息的多種方案。

python.org 網(wǎng)站已在 meta 標簽中指明，采用的是 utf-8 編碼，因此這里將用同樣的格式對字節(jié)串進行解碼。

>>> with urllib.request.urlopen('http://www.python.org/') as f:
...     print(f.read(100).decode('utf-8'))
...
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtm

不用 context manager 方法也能獲得同樣的結(jié)果：

>>> import urllib.request
>>> f = urllib.request.urlopen('http://www.python.org/')
>>> print(f.read(100).decode('utf-8'))
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtm

以下示例將會把數(shù)據(jù)流發(fā)送給某 CGI 的 stdin，并讀取返回數(shù)據(jù)。請注意，該示例只能工作于 Python 裝有 SSL 支持的環(huán)境。

>>> import urllib.request
>>> req = urllib.request.Request(url='https://localhost/cgi-bin/test.cgi',
...                       data=b'This data is passed to stdin of the CGI')
>>> with urllib.request.urlopen(req) as f:
...     print(f.read().decode('utf-8'))
...
Got Data: "This data is passed to stdin of the CGI"

上述示例中的 CGI 代碼如下所示：

#!/usr/bin/env python
import sys
data = sys.stdin.read()
print('Content-type: text/plain\n\nGot Data: "%s"' % data)

下面是利用 Request 發(fā)送``PUT`` 請求的示例：

import urllib.request
DATA = b'some data'
req = urllib.request.Request(url='http://localhost:8080', data=DATA, method='PUT')
with urllib.request.urlopen(req) as f:
    pass
print(f.status)
print(f.reason)

基本 HTTP 認證示例：

import urllib.request
# Create an OpenerDirector with support for Basic HTTP Authentication...
auth_handler = urllib.request.HTTPBasicAuthHandler()
auth_handler.add_password(realm='PDQ Application',
                          uri='https://mahler:8092/site-updates.py',
                          user='klem',
                          passwd='kadidd!ehopper')
opener = urllib.request.build_opener(auth_handler)
# ...and install it globally so it can be used with urlopen.
urllib.request.install_opener(opener)
urllib.request.urlopen('http://www.example.com/login.html')

build_opener() 默認提供了很多現(xiàn)成的 handler，包括 ProxyHandler。 默認情況下，ProxyHandler 會使用名為 <scheme>_proxy 的環(huán)境變量，其中的 <scheme> 是相關(guān)的 URL 協(xié)議。 例如，可以讀取 http_proxy 環(huán)境變量來獲取 HTTP 代理的 URL。

以下示例將默認的 ProxyHandler 替換為自己的 handler，由程序提供代理 URL，并利用 ProxyBasicAuthHandler 加入代理認證的支持：

proxy_handler = urllib.request.ProxyHandler({'http': 'http://www.example.com:3128/'})
proxy_auth_handler = urllib.request.ProxyBasicAuthHandler()
proxy_auth_handler.add_password('realm', 'host', 'username', 'password')

opener = urllib.request.build_opener(proxy_handler, proxy_auth_handler)
# This time, rather than install the OpenerDirector, we use it directly:
opener.open('http://www.example.com/login.html')

添加 HTTP 頭部信息：

可利用 Request 構(gòu)造函數(shù)的 headers 參數(shù)，或者是：

import urllib.request
req = urllib.request.Request('http://www.example.com/')
req.add_header('Referer', 'http://www.python.org/')
# Customize the default User-Agent header value:
req.add_header('User-Agent', 'urllib-example/0.1 (Contact: . . .)')
r = urllib.request.urlopen(req)

OpenerDirector 自動會在每個 Request 中加入一項 User-Agent 頭部信息。若要修改，請參見以下語句：

import urllib.request
opener = urllib.request.build_opener()
opener.addheaders = [('User-agent', 'Mozilla/5.0')]
opener.open('http://www.example.com/')

另請記得，當 Request 傳給 urlopen() （或 OpenerDirector.open()）時，會加入一些標準的頭部信息（ Content-Length 、 Content-Type 和 Host）。

以下會話示例用 GET 方法讀取包含參數(shù)的 URL。

>>> import urllib.request
>>> import urllib.parse
>>> params = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> url = "http://www.musi-cal.com/cgi-bin/query?%s" % params
>>> with urllib.request.urlopen(url) as f:
...     print(f.read().decode('utf-8'))
...

以下示例換用 POST 方法。請注意 urlencode 輸出結(jié)果先被編碼為字節(jié)串 data，再送入 urlopen。

>>> import urllib.request
>>> import urllib.parse
>>> data = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> data = data.encode('ascii')
>>> with urllib.request.urlopen("http://requestb.in/xrbl82xr", data) as f:
...     print(f.read().decode('utf-8'))
...

以下示例顯式指定了 HTTP 代理，以覆蓋環(huán)境變量中的設置：

>>> import urllib.request
>>> proxies = {'http': 'http://proxy.example.com:8080/'}
>>> opener = urllib.request.FancyURLopener(proxies)
>>> with opener.open("http://www.python.org") as f:
...     f.read().decode('utf-8')
...

以下示例根本不用代理，也覆蓋了環(huán)境變量中的設置：

>>> import urllib.request
>>> opener = urllib.request.FancyURLopener({})
>>> with opener.open("http://www.python.org/") as f:
...     f.read().decode('utf-8')
...

已停用的接口?

以下函數(shù)和類是由 Python 2 模塊 urllib``（相對早于 ``urllib2 ）移植過來的。將來某個時候可能會停用。

urllib.request.urlretrieve(url, filename=None, reporthook=None, data=None)?

將 URL 形式的網(wǎng)絡對象復制為本地文件。如果 URL 指向本地文件，則必須提供文件名才會執(zhí)行復制。返回值為元組 (filename, headers) ，其中 filename 是保存網(wǎng)絡對象的本地文件名， headers 是由 urlopen() 返回的遠程對象 info() 方法的調(diào)用結(jié)果。可能觸發(fā)的異常與 urlopen() 相同。

第二個參數(shù)指定文件的保存位置（若未給出，則會是名稱隨機生成的臨時文件）。第三個參數(shù)是個可調(diào)用對象，在建立網(wǎng)絡連接時將會調(diào)用一次，之后每次讀完數(shù)據(jù)塊后會調(diào)用一次。該可調(diào)用對象將會傳入 3 個參數(shù)：已傳輸?shù)膲K數(shù)、塊的大?。ㄒ宰止?jié)為單位）和文件總的大小。如果面對的是老舊 FTP 服務器，文件大小參數(shù)可能會是 -1 ，這些服務器響應讀取請求時不會返回文件大小。

以下例子演示了大部分常用場景：

>>>

>>> import urllib.request
>>> local_filename, headers = urllib.request.urlretrieve('http://python.org/')
>>> html = open(local_filename)
>>> html.close()

如果 url 使用 http: 方式的標識符，則可能給出可選的 data 參數(shù)來指定一個 POST 請求 (通常的請求類型為 GET)。 data 參數(shù)必須是標準 application/x-www-form-urlencoded 格式的字節(jié)串對象；參見 urllib.parse.urlencode() 函數(shù)。

urlretrieve() 在檢測到可用數(shù)據(jù)少于預期的大?。从?Content-Length 標頭所報告的大小）時將引發(fā) ContentTooShortError。 例如，這可能會在下載中斷時發(fā)生。

Content-Length 會被視為大小的下限：如果存在更多的可用數(shù)據(jù)，urlretrieve 會讀取更多的數(shù)據(jù)，但是如果可用數(shù)據(jù)少于該值，則會引發(fā)異常。

在這種情況下你仍然能夠獲取已下載的數(shù)據(jù)，它會存放在異常實例的 content 屬性中。

如果未提供 Content-Length 標頭，urlretrieve 就無法檢查它所下載的數(shù)據(jù)大小，只是簡單地返回它。 在這種情況下你只能假定下載是成功的。

urllib.request.urlcleanup()?

清理之前調(diào)用 urlretrieve() 時可能留下的臨時文件。

class urllib.request.URLopener(proxies=None, **x509)?

3.3 版后已移除.

用于打開和讀取 URL 的基類。 除非你需要支持使用 http:, ftp: 或 file: 以外的方式來打開對象，那你也許可以使用 FancyURLopener。

在默認情況下，URLopener 類會發(fā)送一個內(nèi)容為 urllib/VVV 的 User-Agent 標頭，其中 VVV 是 urllib 的版本號。 應用程序可以通過子類化 URLopener 或 FancyURLopener 并在子類定義中將類屬性 version 設為適當?shù)淖址祦矶x自己的 User-Agent 標頭。

可選的 proxies 形參應當是一個將方式名稱映射到代理 URL 的字典，如為空字典則會完全關(guān)閉代理。 它的默認值為 None，在這種情況下如果存在環(huán)境代理設置則將使用它，正如上文 urlopen() 的定義中所描述的。

一些歸屬于 x509 的額外關(guān)鍵字形參可在使用 https: 方式時被用于客戶端的驗證。 支持通過關(guān)鍵字 key_file 和 cert_file 來提供 SSL 密鑰和證書；對客戶端驗證的支持需要提供這兩個形參。

如果服務器返回錯誤代碼則 URLopener 對象將引發(fā) OSError 異常。

open(fullurl, data=None)?

使用適當?shù)膮f(xié)議打開 fullurl。 此方法會設置緩存和代理信息，然后調(diào)用適當?shù)拇蜷_方法并附帶其輸入?yún)?shù)。 如果方式無法被識別，則會調(diào)用 open_unknown()。 data 參數(shù)的含義與 urlopen() 中的 data 參數(shù)相同。

此方法總是會使用 quote() 來對 fullurl 進行轉(zhuǎn)碼。

open_unknown(fullurl, data=None)?

用于打開未知 URL 類型的可重載接口。

retrieve(url, filename=None, reporthook=None, data=None)?

提取 url 的內(nèi)容并將其存放到 filename 中。 返回值為元組，由一個本地文件名和一個包含響應標頭 (對于遠程 URL) 的 email.message.Message 對象或者 None (對于本地 URL)。 之后調(diào)用方必須打開并讀取 filename 的內(nèi)容。 如果 filename 未給出并且 URL 指向一個本地文件，則會返回輸入文件名。 如果 URL 非本地并且 filename 未給出，則文件名為帶有與輸入 URL 的路徑末尾部分后綴相匹配的后綴的 tempfile.mktemp() 的輸出。 如果給出了 reporthook，它必須為接受三個數(shù)字形參的函數(shù)：數(shù)據(jù)分塊編號、讀入分塊的最大數(shù)據(jù)量和下載的總數(shù)據(jù)量 (未知則為 -1)。 它將在開始時和從網(wǎng)絡讀取每個數(shù)據(jù)分塊之后被調(diào)用。 對于本地 URL reporthook 會被忽略。

如果 url 使用 http: 方式的標識符，則可能給出可選的 data 參數(shù)來指定一個 POST 請求 (通常的請求類型為 GET)。 data 參數(shù)必須為標準的 application/x-www-form-urlencoded 格式 ；參見 urllib.parse.urlencode() 函數(shù)。

version?

指明打開器對象的用戶代理名稱的變量。 以便讓 urllib 告訴服務器它是某個特定的用戶代理，請在子類中將其作為類變量來設置或是在調(diào)用基類構(gòu)造器之前在構(gòu)造器中設置。

class urllib.request.FancyURLopener(...)?

3.3 版后已移除.

FancyURLopener 子類化了 URLopener 以提供對以下 HTTP 響應代碼的默認處理: 301, 302, 303, 307 和 401。 對于上述的 30x 響應代碼，會使用 Location 標頭來獲取實際 URL。 對于 401 響應代碼 (authentication required)，則會執(zhí)行基本 HTTP 驗證。 對于 30x 響應代碼，遞歸層數(shù)會受 maxtries 屬性值的限制，該值默認為 10。

對于所有其他響應代碼，會調(diào)用 http_error_default() 方法，你可以在子類中重載此方法來正確地處理錯誤。

備注

根據(jù) RFC 2616 的說明，對 POST 請求的 301 和 302 響應不可在未經(jīng)用戶確認的情況下自動進行重定向。 在現(xiàn)實情況下，瀏覽器確實允許自動重定義這些響應，將 POST 更改為 GET，于是 urllib 就會復現(xiàn)這種行為。

傳給此構(gòu)造器的形參與 URLopener 的相同。

備注

當執(zhí)行基本驗證時，FancyURLopener 實例會調(diào)用其 prompt_user_passwd() 方法。 默認的實現(xiàn)將向用戶詢問控制終端所要求的信息。 如有必要子類可以重載此方法來支持更適當?shù)男袨椤?/p>

FancyURLopener 類附帶了一個額外方法，它應當被重載以提供適當?shù)男袨?

prompt_user_passwd(host, realm)?

返回指定的安全體系下在給定的主機上驗證用戶所需的信息。 返回的值應當是一個元組 (user, password)，它可被用于基本驗證。

該實現(xiàn)會在終端上提示此信息；應用程序應當重載此方法以使用本地環(huán)境下適當?shù)慕换ツＰ汀?/p>

urllib.request 的限制?

• 目前，僅支持下列協(xié)議: HTTP (0.9 和 1.0 版), FTP, 本地文件, 以及數(shù)據(jù) URL。

  在 3.4 版更改: 增加了對數(shù)據(jù)URL 的支持。

• urlretrieve() 的緩存特性已被禁用，等待有人有時間去正確地解決過期時間標頭的處理問題。

• 應當有一個函數(shù)來查詢特定 URL 是否在緩存中。

• 為了保持向下兼容性，如果某個 URL 看起來是指向本地文件但該文件無法被打開，則該 URL 會使用 FTP 協(xié)議來重新解讀。 這有時可能會導致令人迷惑的錯誤消息。

• urlopen() 和 urlretrieve() 函數(shù)在等待網(wǎng)絡連接建立時會導致任意長時間的延遲。 這意味著在不使用線程的情況下搭建一個可交互的 Web 客戶端是非常困難的。

• 由 urlopen() 或 urlretrieve() 返回的數(shù)據(jù)就是服務器所返回的原始數(shù)據(jù)。 這可以是二進制數(shù)據(jù)（如圖片）、純文本或 HTML 代碼等。 HTTP 協(xié)議在響應標頭中提供了類型信息，這可以通過讀取 Content-Type 標頭來查看。 如果返回的數(shù)據(jù)是 HTML，你可以使用 html.parser 模塊來解析它。

• 處理 FTP 協(xié)議的代碼無法區(qū)分文件和目錄。 這在嘗試讀取指向不可訪問的 URL 時可能導致意外的行為。 如果 URL 以一個 / 結(jié)束，它會被認為指向一個目錄并將作相應的處理。 但是如果讀取一個文件的嘗試導致了 550 錯誤（表示 URL 無法找到或不可訪問，這常常是由于權(quán)限原因），則該路徑會被視為一個目錄以便處理 URL 是指定一個目錄但略去了末尾 / 的情況。 這在你嘗試獲取一個因其設置了讀取權(quán)限因而無法訪問的文件時會造成誤導性的結(jié)果；FTP 代碼將嘗試讀取它，因 550 錯誤而失敗，然后又為這個不可讀取的文件執(zhí)行目錄列表操作。 如果需要細粒度的控制，請考慮使用 ftplib 模塊，子類化 FancyURLopener，或是修改 _urlopener 來滿足你的需求。