Request 對(duì)象?

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

Request.full_url?

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

在 3.4 版更改.

Request.full_url 是一個(gè)帶有 setter、getter 和 deleter 的屬性。讀取 full_url 屬性將會(huì)返回附帶片段（fragment）的初始請(qǐng)求 URL。

Request.type?

URI 方式。

Request.host?

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

Request.origin_req_host?

請(qǐng)求的原始主機(jī)，不含端口。

Request.selector?

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

Request.data?

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

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

Request.unverifiable?

布爾值，標(biāo)識(shí)本請(qǐng)求是否屬于 RFC 2965 中定義的無(wú)法驗(yàn)證的情況。

Request.method?

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

3.3 新版功能.

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

Request.get_method()?

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

在 3.3 版更改: 現(xiàn)在 get_method 會(huì)兼顧 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)?

添加一項(xiàng)不會(huì)被加入重定向請(qǐng)求的頭部信息。

Request.has_header(header)?

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

Request.remove_header(header)?

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

3.4 新版功能.

Request.get_full_url()?

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

在 3.4 版更改.

返回 Request.full_url

Request.set_proxy(host, type)?

連接代理服務(wù)器，為當(dāng)前請(qǐng)求做準(zhǔn)備。 host 和 type 將會(huì)取代本實(shí)例中的對(duì)應(yīng)值，selector 將會(huì)是構(gòu)造函數(shù)中給出的初始 URL。

Request.get_header(header_name, default=None)?

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

Request.header_items()?

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

OpenerDirector 對(duì)象?

OpenerDirector 實(shí)例有以下方法：

OpenerDirector.add_handler(handler)?

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

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

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

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

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

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

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

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

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

  更多信息請(qǐng)參閱 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é)議的錯(cuò)誤。將用給定的參數(shù)（協(xié)議相關(guān)）調(diào)用已注冊(cè)的給定協(xié)議的錯(cuò)誤處理程序。HTTP 協(xié)議是特殊情況，采用 HTTP 響應(yīng)碼來(lái)確定具體的錯(cuò)誤處理程序；請(qǐng)參考 handler 類的 http_error_<type>() 方法。

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

OpenerDirector 對(duì)象分 3 個(gè)階段打開 URL：

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

1. 每個(gè)具有 _request() 這類方法的 handler 都會(huì)調(diào)用本方法對(duì)請(qǐng)求進(jìn)行預(yù)處理。

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

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

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

3. 每個(gè)具有 _response() 這類方法的 handler 都會(huì)調(diào)用這些方法，以對(duì)響應(yīng)進(jìn)行后處理。

BaseHandler 對(duì)象?

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

BaseHandler.add_parent(director)?

將 director 加為父 OpenerDirector。

BaseHandler.close()?

移除所有父 OpenerDirector。

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

BaseHandler.parent?

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

BaseHandler.default_open(req)?

本方法在 BaseHandler 中 未 予定義，但其子類若要捕獲所有 URL 則應(yīng)進(jìn)行定義。

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).

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

BaseHandler.<protocol>_open(req)

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

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

BaseHandler.unknown_open(req)?

本方法在 BaseHandler 中 未 予定義，但其子類若要捕獲并打開所有未注冊(cè) handler 的 URL，則應(yīng)進(jìn)行定義。

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

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

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

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

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

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

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

子類應(yīng)該重寫本方法，以便能處理相應(yīng)的 HTTP 錯(cuò)誤。

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

BaseHandler.<protocol>_request(req)

本方法在 BaseHandler 中 未 予定義，但其子類若要對(duì)給定協(xié)議的請(qǐng)求進(jìn)行預(yù)處理，則應(yīng)進(jìn)行定義。

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

BaseHandler.<protocol>_response(req, response)

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

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

HTTPRedirectHandler 對(duì)象?

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

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

備注

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

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

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

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

與 http_error_301() 相同，不過(guò)是發(fā)生“found”響應(yīng)時(shí)的調(diào)用。

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

與 http_error_301() 相同，不過(guò)是發(fā)生“see other”響應(yīng)時(shí)的調(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 對(duì)象?

HTTPCookieProcessor 的實(shí)例具備一個(gè)屬性：

HTTPCookieProcessor.cookiejar?

cookie 存放在 http.cookiejar.CookieJar 中。

ProxyHandler 對(duì)象?

ProxyHandler.<protocol>_open(request)

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

HTTPPasswordMgr 對(duì)象?

以下方法 HTTPPasswordMgr 和 HTTPPasswordMgrWithDefaultRealm 對(duì)象均有提供。

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

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

HTTPPasswordMgr.find_user_password(realm, authuri)?

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

對(duì)于 HTTPPasswordMgrWithDefaultRealm 對(duì)象，如果給定 realm 沒(méi)有匹配的用戶名和密碼，將搜索 realm None。

HTTPPasswordMgrWithPriorAuth 對(duì)象?

這是 HTTPPasswordMgrWithDefaultRealm 的擴(kuò)展，以便對(duì)那些需要一直發(fā)送認(rèn)證憑證的 URI 進(jìn)行跟蹤。

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

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

HTTPPasswordMgrWithPriorAuth.find_user_password(realm, authuri)?

與 HTTPPasswordMgrWithDefaultRealm 對(duì)象的相同。

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

更新給定 uri 或 URI 列表的 is_authenticated 標(biāo)志。

HTTPPasswordMgrWithPriorAuth.is_authenticated(self, authuri)?

返回給定 URI is_authenticated 標(biāo)志的當(dāng)前狀態(tài)。

AbstractBasicAuthHandler 對(duì)象?

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

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

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

HTTPBasicAuthHandler 對(duì)象?

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

如果可用的話，請(qǐng)用身份認(rèn)證信息重試請(qǐng)求。

ProxyBasicAuthHandler 對(duì)象?

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

如果可用的話，請(qǐng)用身份認(rèn)證信息重試請(qǐng)求。

AbstractDigestAuthHandler 對(duì)象?

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

authreq 應(yīng)為請(qǐng)求中有關(guān) realm 的頭部信息名稱，host 應(yīng)為需要進(jìn)行身份認(rèn)證的主機(jī)，req 應(yīng)為（已失敗的） Request 對(duì)象， headers 則應(yīng)為出錯(cuò)的頭部信息。

HTTPDigestAuthHandler 對(duì)象?

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

如果可用的話，請(qǐng)用身份認(rèn)證信息重試請(qǐng)求。

ProxyDigestAuthHandler 對(duì)象?

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

如果可用的話，請(qǐng)用身份認(rèn)證信息重試請(qǐng)求。

HTTPHandler 對(duì)象?

HTTPHandler.http_open(req)?

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

HTTPSHandler 對(duì)象?

HTTPSHandler.https_open(req)?

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

FileHandler 對(duì)象?

FileHandler.file_open(req)?

若無(wú)主機(jī)名或主機(jī)名為 'localhost' ，則打開本地文件。

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

DataHandler 對(duì)象?

DataHandler.data_open(req)?

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

FTPHandler 對(duì)象?

FTPHandler.ftp_open(req)?

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

CacheFTPHandler 對(duì)象?

CacheFTPHandler 對(duì)象即為加入以下方法的 FTPHandler 對(duì)象：

CacheFTPHandler.setTimeout(t)?

設(shè)置連接超時(shí)為 t 秒。

CacheFTPHandler.setMaxConns(m)?

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

UnknownHandler 對(duì)象?

UnknownHandler.unknown_open()?

觸發(fā) URLError 異常。

HTTPErrorProcessor 對(duì)象?

HTTPErrorProcessor.http_response(request, response)?

處理出錯(cuò)的 HTTP 響應(yīng)。

對(duì)于 200 錯(cuò)誤碼，響應(yīng)對(duì)象應(yīng)立即返回。

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

HTTPErrorProcessor.https_response(request, response)?

HTTPS 出錯(cuò)響應(yīng)的處理。

與 http_response() 方法相同。

例子?

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

以下示例將讀取 python.org 主頁(yè)并顯示前 300 個(gè)字節(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 '

請(qǐng)注意，urlopen 將返回字節(jié)對(duì)象。這是因?yàn)?urlopen 無(wú)法自動(dòng)確定由 HTTP 服務(wù)器收到的字節(jié)流的編碼。通常，只要能確定或猜出編碼格式，就應(yīng)將返回的字節(jié)對(duì)象解碼為字符串。

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

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

>>> 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

以下示例將會(huì)把數(shù)據(jù)流發(fā)送給某 CGI 的 stdin，并讀取返回?cái)?shù)據(jù)。請(qǐng)注意，該示例只能工作于 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`` 請(qǐng)求的示例：

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 認(rèn)證示例：

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

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

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 自動(dòng)會(huì)在每個(gè) Request 中加入一項(xiàng) User-Agent 頭部信息。若要修改，請(qǐng)參見以下語(yǔ)句：

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

另請(qǐng)記得，當(dāng) Request 傳給 urlopen() （或 OpenerDirector.open()）時(shí)，會(huì)加入一些標(biāo)準(zhǔn)的頭部信息（ Content-Length 、 Content-Type 和 Host）。

以下會(huì)話示例用 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 方法。請(qǐng)注意 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)境變量中的設(shè)置：

>>> 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)境變量中的設(shè)置：

>>> 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``（相對(duì)早于 ``urllib2 ）移植過(guò)來(lái)的。將來(lái)某個(gè)時(shí)候可能會(huì)停用。

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

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

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

以下例子演示了大部分常用場(chǎng)景：

>>>

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

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

urlretrieve() 在檢測(cè)到可用數(shù)據(jù)少于預(yù)期的大小（即由 Content-Length 標(biāo)頭所報(bào)告的大?。r(shí)將引發(fā) ContentTooShortError。 例如，這可能會(huì)在下載中斷時(shí)發(fā)生。

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

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

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

urllib.request.urlcleanup()?

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

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

3.3 版后已移除.

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

在默認(rèn)情況下，URLopener 類會(huì)發(fā)送一個(gè)內(nèi)容為 urllib/VVV 的 User-Agent 標(biāo)頭，其中 VVV 是 urllib 的版本號(hào)。 應(yīng)用程序可以通過(guò)子類化 URLopener 或 FancyURLopener 并在子類定義中將類屬性 version 設(shè)為適當(dāng)?shù)淖址祦?lái)定義自己的 User-Agent 標(biāo)頭。

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

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

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

open(fullurl, data=None)?

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

此方法總是會(huì)使用 quote() 來(lái)對(duì) fullurl 進(jìn)行轉(zhuǎn)碼。

open_unknown(fullurl, data=None)?

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

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

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

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

version?

指明打開器對(duì)象的用戶代理名稱的變量。 以便讓 urllib 告訴服務(wù)器它是某個(gè)特定的用戶代理，請(qǐng)?jiān)谧宇愔袑⑵渥鳛轭愖兞縼?lái)設(shè)置或是在調(diào)用基類構(gòu)造器之前在構(gòu)造器中設(shè)置。

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

3.3 版后已移除.

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

對(duì)于所有其他響應(yīng)代碼，會(huì)調(diào)用 http_error_default() 方法，你可以在子類中重載此方法來(lái)正確地處理錯(cuò)誤。

備注

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

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

備注

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

FancyURLopener 類附帶了一個(gè)額外方法，它應(yīng)當(dāng)被重載以提供適當(dāng)?shù)男袨?

prompt_user_passwd(host, realm)?

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

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

urllib.request 的限制?

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

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

• urlretrieve() 的緩存特性已被禁用，等待有人有時(shí)間去正確地解決過(guò)期時(shí)間標(biāo)頭的處理問(wèn)題。

• 應(yīng)當(dāng)有一個(gè)函數(shù)來(lái)查詢特定 URL 是否在緩存中。

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

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

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

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