21.6. urllib.request
--- URL を開くための拡張可能なライブラリ¶
ソースコード: Lib/urllib/request.py
urllib.request
モジュールは基本的な認証、暗号化認証、リダイレクション、Cookie、その他の介在する複雑なアクセス環境において (大抵は HTTP で) URL を開くための関数とクラスを定義します。
参考
より高水準の HTTP クライアントインターフェイスとしては Requests パッケージ がお奨めです。
urllib.request
モジュールでは以下の関数を定義しています:
-
urllib.request.
urlopen
(url, data=None, [timeout, ]*, cafile=None, capath=None, cadefault=False, context=None)¶ URL url を開きます。 url は文字列でも
Request
オブジェクトでもかまいません。data はサーバーに送信する追加データを指定するオブジェクトであるか
None
である必要があります。詳細はRequest
を確認してください。urllib.request モジュールは HTTP/1.1 を使用し、その HTTP リクエストに
Connection:close
ヘッダーを含みます。任意引数 timeout には接続開始などのブロックする操作におけるタイムアウト時間を秒数で指定します (指定されなかった場合、グローバルのデフォルトタイムアウト時間が利用されます)。この引数は、 HTTP, HTTPS, FTP 接続でのみ有効です。
context を指定する場合は、様々な SSL オプションを記述する
ssl.SSLContext
インスタンスでなければなりません。 詳細はHTTPSConnection
を参照してください。任意引数 cafile および capath には HTTPS リクエストのための CA 証明書のセットを指定します。cafile には CA 証明書のリストを含む 1 個のファイルを指定し、capath にはハッシュ化された証明書ファイルが格納されたディレクトリを指定しなければなりません。より詳しい情報は
ssl.SSLContext.load_verify_locations()
を参照してください。cadefault 引数は無視されます。
この関数は常に コンテクストマネージャ として機能するオブジェクトを返します。このオブジェクトには以下のメソッドがあります。
geturl()
--- 取得されたリソースの URL を返します。 主に、リダイレクトが発生したかどうかを確認するために利用しますinfo()
--- 取得されたページのヘッダーなどのメタ情報を、email.message_from_string()
インスタンスとして返します。 (Quick Reference to HTTP Headers を参照してください)getcode()
-- レスポンスの HTTP ステータスコードです。
HTTP および HTTPS URL の場合、この関数は、わずかに修正された
http.client.HTTPResponse
オブジェクトを返します。上記の3つの新しいメソッドに加えて、 msg 属性がHTTPResponse
のドキュメンテーションで指定されているレスポンスヘッダーの代わりにreason
属性 --- サーバーから返された reason フレーズ --- と同じ情報を含んでいます。FTP 、ファイルおよびデータ URL 、レガシーな
URLopener
やFancyURLopener
によって明示的に扱われるリクエストの場合、この関数はurllib.response.addinfourl
オブジェクトを返します。プロトコルエラー発生時は
URLError
を送出します。どのハンドラもリクエストを処理しなかった場合には
None
を返すことがあるので注意してください (デフォルトでインストールされる グローバルハンドラのOpenerDirector
は、UnknownHandler
を使って上記の問題が起きないようにしています)。さらに、プロキシ設定が検出された場合(例えば
http_proxy
のような*_proxy
環境変数がセットされているなど)にはProxyHandler
がデフォルトでインストールされ、これがプロキシを通してリクエストを処理するようにしています。Python 2.6 以前のレガシーな
urllib.urlopen
関数は廃止されました。urllib.request.urlopen()
が過去のurllib2.urlopen
に相当します。urllib.urlopen
において辞書型オブジェクトで渡していたプロキシの扱いは、ProxyHandler
オブジェクトを使用して取得できます。バージョン 3.2 で変更: cafile および capath が追加されました。
バージョン 3.2 で変更: HTTPS バーチャルホストがサポートされました (
ssl.HAS_SNI
が真の場合のみ)。バージョン 3.2 で追加: data にイテラブルなオブジェクトを指定できるようになりました。
バージョン 3.3 で変更: cadefault が追加されました。
バージョン 3.4.3 で変更: context が追加されました。
バージョン 3.6 で非推奨: cafile, capath および cadefault は非推奨となったので、 context を使ってください。 代わりに
ssl.SSLContext.load_cert_chain()
を使うか、またはssl.create_default_context()
にシステムが信頼する CA 証明書を選んでもらうかしてください。
-
urllib.request.
install_opener
(opener)¶ 指定された
OpenerDirector
のインスタンスを、デフォルトで利用されるグローバルの opener としてインストールします。 opener のインストールは、 urlopen にその opener を使って欲しいとき以外必要ありません。普段は単にurlopen()
の代わりにOpenerDirector.open()
を利用してください。この関数は引数が本当にOpenerDirector
のインスタンスであるかどうかはチェックしません。適切なインタフェースを持った任意のクラスを利用することができます。
-
urllib.request.
build_opener
([handler, ...])¶ 与えられた順番に URL ハンドラを連鎖させる
OpenerDirector
のインスタンスを返します。 handler はBaseHandler
またはBaseHandler
のサブクラスのインスタンスのどちらかです (どちらの場合も、コンストラクトは引数無しで呼び出せるようになっていなければなりません) 。クラスProxyHandler
(proxy 設定が検出された場合),UnknownHandler
,HTTPHandler
,HTTPDefaultErrorHandler
,HTTPRedirectHandler
,FTPHandler
,FileHandler
,HTTPErrorProcessor
については、そのクラスのインスタンスか、そのサブクラスのインスタンスが handler に含まれていない限り、 handler よりも先に連鎖します。Python が SSL をサポートするように設定してインストールされている場合 (すなわち、
ssl
モジュールを import できる場合)HTTPSHandler
も追加されます。BaseHandler
サブクラスでもhandler_order
メンバー変数を変更して、ハンドラーリスト内での場所を変更できます。
-
urllib.request.
pathname2url
(path)¶ ローカルシステムにおける記法で表されたパス名 path をURL におけるパス部分の形式に変換します。これは完全な URL を生成するわけではありません。戻り値は
quote()
関数によってクオートされています。
-
urllib.request.
url2pathname
(path)¶ URL の、パーセントエンコードされたパス部分 path をローカルシステムの記法に変換します。これは完全な URL を受け付けません。path のデコードには
unquote()
関数を使用します。
-
urllib.request.
getproxies
()¶ このヘルパー関数はスキーマからプロキシサーバーのURLへのマッピングを行う辞書を返します。この関数はまず、どのOSでも最初に
<scheme>_proxy
という名前の環境変数を大文字小文字を区別せずにスキャンします。そこで見つからなかった場合、 Max OS X の場合は Mac OSX システム環境設定を、 Windows の場合はシステムレジストリを参照します。もし小文字と大文字の環境変数が両方存在する (そして値が一致しない) なら、小文字の環境変数が優先されます。注釈
もし環境変数
REQUEST_METHOD
が設定されていたら (これは通常スクリプトが CGI 環境で動いていることを示しています)、環境変数HTTP_PROXY
(大文字の_PROXY
) は無視されます。その理由は、クライアントが "Proxy:" HTTP ヘッダーを使ってこの環境変数を注入できるからです。もし CGI 環境で HTTP プロキシを使う必要があれば、ProxyHandler
を明示的に使用するか、環境変数名を小文字にしてください (あるいは、少なくともサフィックスを_proxy
にしてください) 。
以下のクラスが提供されています:
-
class
urllib.request.
Request
(url, data=None, headers={}, origin_req_host=None, unverifiable=False, method=None)¶ このクラスは URL リクエストを抽象化したものです。
url は有効な URL を指す文字列でなくてはなりません。
data must be an object specifying additional data to send to the server, or
None
if no such data is needed. Currently HTTP requests are the only ones that use data. The supported object types include bytes, file-like objects, and iterables. If noContent-Length
norTransfer-Encoding
header field has been provided,HTTPHandler
will set these headers according to the type of data.Content-Length
will be used to send bytes objects, whileTransfer-Encoding: chunked
as specified in RFC 7230, Section 3.3.1 will be used to send files and other iterables.For an HTTP POST request method, data should be a buffer in the standard application/x-www-form-urlencoded format. The
urllib.parse.urlencode()
function takes a mapping or sequence of 2-tuples and returns an ASCII string in this format. It should be encoded to bytes before being used as the data parameter.headers は辞書でなければなりません。この辞書は
add_header()
を辞書のキーおよび値を引数として呼び出した時と同じように扱われます。この引数は、多くの場合ブラウザーが何であるかを特定するUser-Agent
ヘッダーの値を "偽装" するために用いられます。これは一部の HTTP サーバーが、スクリプトからのアクセスを禁止するために一般的なブラウザーのUser-Agent
ヘッダーしか許可しないためです。例えば、 Mozilla Firefox はUser-Agent
に"Mozilla/5.0 (X11; U; Linux i686) Gecko/20071127 Firefox/2.0.0.11"
のように設定し、urllib
はデフォルトで"Python-urllib/2.6"
(Python 2.6の場合) と設定します。An appropriate
Content-Type
header should be included if the data argument is present. If this header has not been provided and data is not None,Content-Type: application/x-www-form-urlencoded
will be added as a default.最後の二つの引数は、サードパーティの HTTP クッキーを正しく扱いたい場合にのみ関係してきます:
origin_req_host は、 RFC 2965 で定義されている元のトランザクションにおけるリクエストホスト (request-host of the origin transaction) です。デフォルトの値は
http.cookiejar.request_host(self)
です。この値は、ユーザーによって開始された元々のリクエストにおけるホスト名や IP アドレスです。例えば、もしリクエストがある HTML ドキュメント内の画像を指していれば、この値は画像を含んでいるページへのリクエストにおけるリクエストホストになるはずです。unverifiable は、 RFC 2965 の定義において、該当するリクエストが証明不能 (unverifiable) であるかどうかを示します。デフォルトの値は
False
です。証明不能なリクエストとは、ユーザが受け入れの可否を選択できないような URL を持つリクエストのことです。例えば、リクエストが HTML ドキュメント中の画像であり、ユーザがこの画像を自動的に取得するか どうかを選択できない場合には、証明不能フラグは True になります。method should be a string that indicates the HTTP request method that will be used (e.g.
'HEAD'
). If provided, its value is stored in themethod
attribute and is used byget_method()
. The default is'GET'
if data isNone
or'POST'
otherwise. Subclasses may indicate a different default method by setting themethod
attribute in the class itself.注釈
The request will not work as expected if the data object is unable to deliver its content more than once (e.g. a file or an iterable that can produce the content only once) and the request is retried for HTTP redirects or authentication. The data is sent to the HTTP server right away after the headers. There is no support for a 100-continue expectation in the library.
バージョン 3.3 で変更: 引数
Request.method
が Request クラスに追加されました。バージョン 3.4 で変更:
Request.method
のデフォルト値はクラスレベルで指定されることがあります。バージョン 3.6 で変更: Do not raise an error if the
Content-Length
has not been provided and data is neitherNone
nor a bytes object. Fall back to use chunked transfer encoding instead.
-
class
urllib.request.
OpenerDirector
¶ OpenerDirector
クラスは、BaseHandler
の連鎖的に呼び出して URL を開きます。このクラスはハンドラをどのように連鎖させるか、またどのようにエラーをリカバリするかを管理します。
-
class
urllib.request.
BaseHandler
¶ このクラスはハンドラ連鎖に登録される全てのハンドラがベースとしているクラスです -- このクラスでは登録のための単純なメカニズムだけを扱います。
-
class
urllib.request.
HTTPDefaultErrorHandler
¶ HTTP エラーレスポンスのデフォルトハンドラーを定義するクラスです; すべてのレスポンスは
HTTPError
例外に変換されます。
-
class
urllib.request.
HTTPRedirectHandler
¶ リダイレクションを扱うクラスです。
-
class
urllib.request.
HTTPCookieProcessor
(cookiejar=None)¶ HTTP Cookie を扱うためのクラスです。
-
class
urllib.request.
ProxyHandler
(proxies=None)¶ このクラスはプロキシを通過してリクエストを送らせます。引数 proxies を与える場合、プロトコル名からプロキシの URL へ対応付ける辞書でなくてはなりません。標準では、プロキシのリストを環境変数
<protocol>_proxy
から読み出します。プロキシ環境変数が設定されていない場合は、 Windows 環境では、 レジストリのインターネット設定セクションからプロキシ設定を手に入れ、 Mac OS X 環境では、 OS X システム設定フレームワーク (System Configuration Framework) からプロキシ情報を取得します。自動検出されたproxyを無効にするには、空の辞書を渡してください。
no_proxy
環境変数は、proxyを利用せずにアクセスするべきホストを指定するために利用されます。設定する場合は、カンマ区切りの、ホストネーム suffix のリストで、オプションとして:port
を付けることができます。例えば、cern.ch,ncsa.uiuc.edu,some.host:8080
.注釈
変数
REQUEST_METHOD
が設定されている場合、HTTP_PROXY
は無視されます;getproxies()
のドキュメンテーションを参照してください。
-
class
urllib.request.
HTTPPasswordMgr
¶ (realm, uri) -> (user, password)
の対応付けデータベースを保持します。
-
class
urllib.request.
HTTPPasswordMgrWithDefaultRealm
¶ (realm, uri) -> (user, password)
の対応付けデータベースを保持します。レルムNone
はその他諸々のレルムを表し、他のレルムが該当しない場合に検索されます。
-
class
urllib.request.
HTTPPasswordMgrWithPriorAuth
¶ uri -> is_authenticated
マッピングのデータベースも持つHTTPPasswordMgrWithDefaultRealm
のバリエーションです。最初に401
レスポンスを待つのではなく直ちに認証情報を送るときの条件を判断するために、 BasicAuth ハンドラによって使われます。バージョン 3.5 で追加.
-
class
urllib.request.
AbstractBasicAuthHandler
(password_mgr=None)¶ これは、リモートホストとプロキシの両方に対して HTTP 認証を行うことを助ける mixin クラスです。 password_mgr は、もし与えられたら
HTTPPasswordMgr
と互換性のあるオブジェクトでなければなりません; サポートすべきインタフェースに関する情報は HTTPPasswordMgr オブジェクト 節を参照してください。もし passwd_mgr がis_authenticated
とupdate_authenticated
メソッドも提供するなら (HTTPPasswordMgrWithPriorAuth オブジェクト を参照)、ハンドラは与えられた URI に対するis_authenticated
の結果を用いてリクエストにおいて認証情報を送るかどうかを決定します。もしis_authenticated
がその URI に対してTrue
を返すなら、認証情報が送られます。is_authenticated
がFalse
なら認証情報は送られません。そして、もし401
レスポンスを受け取ったら、認証情報を付けて改めてリクエストが送信されます。もし認証が成功したら、それ以降その URI またはその親 URI に対して行われるリクエストが認証情報を自動的に含むように、 URI に対してis_authenticated
をTrue
に設定するためにupdate_authenticated
が呼ばれます。バージョン 3.5 で追加:
is_authenticated
サポートが追加されました。
-
class
urllib.request.
HTTPBasicAuthHandler
(password_mgr=None)¶ 遠隔ホストとの間での認証を扱います。 password_mgr を与える場合、
HTTPPasswordMgr
と互換性がなければなりません; 互換性のためにサポートしなければならないインタフェースについての情報はセクション HTTPPasswordMgr オブジェクト を参照してください。HTTPBasicAuthHandler は、間違った認証スキーマが与えられるとValueError
を送出します。
-
class
urllib.request.
ProxyBasicAuthHandler
(password_mgr=None)¶ プロキシとの間での認証を扱います。 password_mgr を与える場合、
HTTPPasswordMgr
と互換性が なければなりません; 互換性のためにサポートしなければならないインタフェースについての情報はセクション HTTPPasswordMgr オブジェクト を参照してください。
-
class
urllib.request.
AbstractDigestAuthHandler
(password_mgr=None)¶ このクラスはHTTP 認証を補助するための混ぜ込みクラス (mixin class) です。遠隔ホストとプロキシの両方に対応しています。 password_mgr を与える場合、
HTTPPasswordMgr
と互換性がなければなりません; 互換性のためにサポートしなければならないインタフェースについての情報はセクション HTTPPasswordMgr オブジェクト を参照してください。
-
class
urllib.request.
HTTPDigestAuthHandler
(password_mgr=None)¶ リモートホストとの認証を扱います。password_mgr を与える場合、
HTTPPasswordMgr
と互換性のあるものでなければなりません。サポートしなければならないインターフェースについての情報は HTTPPasswordMgr オブジェクト 節を参照してください。Digest 認証ハンドラーと Basic 認証ハンドラーの両方が追加された場合、常に Digest 認証を先に試みます。Digest 認証が 40x のレスポンスを再び返すと、Basic 認証ハンドラーに送信されます。このハンドラーメソッドは、Digest および Basic 以外の認証スキームが存在する場合はValueError
を送出します。バージョン 3.3 で変更: 未サポートの認証スキームでは
ValueError
を送出するようになりました。
-
class
urllib.request.
ProxyDigestAuthHandler
(password_mgr=None)¶ プロキシとの間での認証を扱います。 password_mgr を与える場合、
HTTPPasswordMgr
と互換性が なければなりません; 互換性のためにサポートしなければならないインタフェースについての情報はセクション HTTPPasswordMgr オブジェクト を参照してください。
-
class
urllib.request.
HTTPHandler
¶ HTTP の URL を開きます。
-
class
urllib.request.
HTTPSHandler
(debuglevel=0, context=None, check_hostname=None)¶ HTTPS で URL を開きます。context および check_hostname は
http.client.HTTPSConnection
のものと同じ意味です。バージョン 3.2 で変更: context および check_hostname が追加されました。
-
class
urllib.request.
FileHandler
¶ ローカルファイルを開きます。
-
class
urllib.request.
DataHandler
¶ data URL を開きます。
バージョン 3.4 で追加.
-
class
urllib.request.
FTPHandler
¶ FTP の URL を開きます。
-
class
urllib.request.
CacheFTPHandler
¶ FTP の URL を開きます。遅延を最小限にするために、開かれている FTP 接続に対するキャッシュを保持します。
-
class
urllib.request.
UnknownHandler
¶ その他諸々のためのクラスで、未知のプロトコルの URL を開きます。
-
class
urllib.request.
HTTPErrorProcessor
¶ HTTP エラー応答の処理をします。
21.6.1. Request オブジェクト¶
以下のメソッドは Request
の公開インターフェースについて説明しています。これらはすべてサブクラスでオーバーライドできます。また、解析したリクエストを調査するためにクライアントで使用するいくつかの属性も定義します。
-
Request.
full_url
¶ コンストラクターに渡されたオリジナルの URL です。
バージョン 3.4 で変更.
Request.full_url は、 setter, getter, deleter を持つプロパティです。もし存在すれば、
full_url
はオリジナルのリクエスト URL フラグメント付きで返します。
-
Request.
type
¶ URI スキームです。
-
Request.
host
¶ URI オーソリティです。通常はホスト名ですが、コロンで区切られたポート番号が付随することもあります。
-
Request.
origin_req_host
¶ リクエストしたオリジナルのホスト名です。ポート番号はつきません。
-
Request.
data
¶ リクエストのエンティティボディか、指定されない場合は
None
になります。バージョン 3.4 で変更:
Request.data
の値が変更されると、もしそれ以前に "Content-Length" ヘッダーの値が設定または計算されていたらヘッダーが削除されるようになりました。
-
Request.
method
¶ HTTP リクエストで使うメソッドです。 デフォルト値は
None
で、このときは使うメソッドをget_method()
が通常の方法で決定するということになります。 この値を設定する (従ってget_method()
のデフォルトの決定を上書きする) 方法は、Request
サブクラスでのクラスレベルの設定処理でデフォルト値を提供するか、Request
のコンストラクタの method 引数へ値を渡すかです。バージョン 3.3 で追加.
バージョン 3.4 で変更: サブクラスでデフォルト値が設定できるようになりました; 以前はコンストラクタ引数からしか設定できませんでした。
-
Request.
get_method
()¶ HTTP リクエストメソッドを示す文字列を返します。
Request.method
がNone
でなければその値を返します。そうでない場合、Request.data
がNone
なら'GET'
を、そうでなければ'POST'
を返します。これは HTTP リクエストに対してのみ意味を持ちます。バージョン 3.3 で変更: get_method は
Request.method
の値を参照するようになりました。
-
Request.
add_header
(key, val)¶ リクエストに新たなヘッダーを追加します。ヘッダーは HTTP ハンドラ以外のハンドラでは無視されます。HTTP ハンドラでは、引数はサーバに送信される ヘッダーのリストに追加されます。同じ名前を持つヘッダを 2 つ以上持つことはできず、 key の衝突が生じた場合、後で追加したヘッダーが前に 追加したヘッダーを上書きします。現時点では、この機能は HTTP の機能を損ねることはありません。というのは、複数回呼び出したときに意味を 持つようなヘッダーには、どれもただ一つのヘッダーを使って同じ機能を果たすための (ヘッダー特有の) 方法があるからです。
-
Request.
add_unredirected_header
(key, header)¶ リダイレクトされたリクエストには追加されないヘッダーを追加します。
-
Request.
has_header
(header)¶ インスタンスが名前つきヘッダーであるかどうかを (通常のヘッダーと非リダイレクトヘッダの両方を調べて) 返します。
-
Request.
remove_header
(header)¶ リクエストインスタンス (の通常のヘッダーと非リダイレクトヘッダーの両方) から名前つきヘッダーを削除します。
バージョン 3.4 で追加.
-
Request.
get_full_url
()¶ コンストラクタで与えられた URL を返します。
バージョン 3.4 で変更.
Request.full_url
を返します。
-
Request.
set_proxy
(host, type)¶ リクエストがプロキシサーバを経由するように準備します。 host および type はインスタンスのもとの設定と置き換えられ ます。インスタンスのセレクタはコンストラクタに与えたもともとの URL になります。
-
Request.
get_header
(header_name, default=None)¶ 指定されたヘッダーの値を返します。ヘッダーがない場合は、 default の値を返します。
-
Request.
header_items
()¶ リクエストヘッダーの値を、タプル (header_name, header_value) のリストで返します。
バージョン 3.4 で変更: 3.3 から非推奨だった Request オブジェクトのメソッド add_data, has_data, get_data, get_type, get_host, get_selector, get_origin_req_host, is_unverifiable が削除されました。
21.6.2. OpenerDirector オブジェクト¶
OpenerDirector
インスタンスは以下のメソッドを持っています:
-
OpenerDirector.
add_handler
(handler)¶ handler は
BaseHandler
のインスタンスでなければなりません。以下のメソッドを使った検索が行われ、URL を取り扱うことが可能なハンドラの連鎖が追加されます (HTTP エラーは特別扱いされているので注意してください)。protocol_open()
--- ハンドラーが protocol の URL を開く方法を知っているかどうかを調べます。http_error_type()
--- ハンドラーが HTTP エラーコード type の処理方法を知っていることを示すシグナルです。protocol_error()
--- ハンドラーが (http
でない) protocol のエラーを処理する方法を知っていることを示すシグナルです。protocol_request()
--- ハンドラーが protocol リクエストのプリプロセス方法を知っていることを示すシグナルです。protocol_response()
--- ハンドラーが protocol リクエストのポストプロセス方法を知っていることを示すシグナルです。
-
OpenerDirector.
open
(url, data=None[, timeout])¶ 与えられた url (リクエストオブジェクトでも文字列でもかまいません) を開きます。オプションとして data を与えることができます。 引数、戻り値、および送出される例外は
urlopen()
と同じです (urlopen()
の場合、標準でインストールされている グローバルなOpenerDirector
のopen()
メソッドを呼び出します) 。 オプションの timeout 引数は、接続開始のようなブロックする処理におけるタイムアウト時間を 秒数で指定します。(指定しなかった場合は、グローバルのデフォルト設定が利用されます) タイムアウト機能は、 HTTP, HTTPS, FTP 接続でのみ有効です。
-
OpenerDirector.
error
(proto, *args)¶ 与えられたプロトコルにおけるエラーを処理します。このメソッドは与えられたプロトコルにおける登録済みのエラーハンドラを (プロトコル固有の) 引数で呼び出します。 HTTP プロトコルは特殊なケースで、特定のエラーハンドラを選び出すのに HTTP レスポンスコードを使います; ハンドラクラスの
http_error_*()
メソッドを参照してください。戻り値および送出される例外は
urlopen()
と同じものです。
OpenerDirector オブジェクトは、以下の 3 つのステージに分けて URL を開きます:
各ステージで OpenerDirector オブジェクトのメソッドがどのような順で呼び出されるかは、ハンドラインスタンスの並び方で決まります。
protocol_request()
形式のメソッドを持つすべてのハンドラーに対してそのメソッドを呼び出し、リクエストのプリプロセスを行います。protocol_open()
のようなメソッドでハンドラーが呼び出され、リクエストを処理します。このステージではハンドラーが非-None
値 (例: レスポンス) か例外 (通常はURLError
) を返した時点で終了します。例外は伝搬できます。実際には、上のアルゴリズムではまず
default_open()
という名前のメソッドを呼び出します。このメソッドがすべてNone
を返す場合、同じアルゴリズムを繰り返して、今度はprotocol_open()
形式のメソッドを試します。メソッドがすべてNone
を返すと、さらに同じアルゴリズムを繰り返してunknown_open()
を呼び出します。これらのメソッドの実装には、親となる
OpenerDirector
インスタンスのopen()
やerror()
といったメソッド呼び出しが入る場合があるので注意してください。protocol_response()
形式のメソッドを持つすべてのハンドラーに対してそのメソッドを呼び出し、リクエストのポストプロセスを行います。
21.6.3. BaseHandler オブジェクト¶
BaseHandler
オブジェクトは直接的に役に立つ 2 つのメソッドと、その他として派生クラスで使われることを想定したメソッドを 提供します。以下は直接的に使うためのメソッドです:
-
BaseHandler.
add_parent
(director)¶ 親オブジェクトとして、
director
を追加します。
-
BaseHandler.
close
()¶ 全ての親オブジェクトを削除します。
以下の属性およびメソッドは BaseHandler
から派生したクラスでのみ使われます。
注釈
慣習的に、 protocol_request()
や protocol_response()
といったメソッドを定義している サブクラスは *Processor
と名づけ、その他は * Handler
と名づけることになっています
-
BaseHandler.
parent
¶ 有効な
OpenerDirector
です。この値は違うプロトコルを使って URL を開く場合やエラーを処理する際に使われます。
-
BaseHandler.
default_open
(req)¶ このメソッドは
BaseHandler
では定義されて いません 。しかし、全ての URL をキャッチさせたいなら、サブクラスで定義する 必要があります。このメソッドが実装されていれば、
OpenerDirector
の親クラスによって呼び出されます。これはOpenerDirector
のopen()
の戻り値で表されるファイルライクオブジェクトか、またはNone
を返さなければならず、真に想定外の事態が発生した場合を除き、URLError
を送出しなければなりません (例えば、MemoryError
はURLError
にマップしてはなりません)。このメソッドはプロトコル固有のオープンメソッドが呼び出される前に呼び出されます。
-
BaseHandler.
protocol_open
(req) このメソッドは
BaseHandler
では定義されて いません 。しかしプロトコルの URL をキャッチしたいなら、サブクラスで定義する必要があります。このメソッドが定義されていた場合、
OpenerDirector
から呼び出されます。戻り値はdefault_open()
と同じでなければなりません。
-
BaseHandler.
unknown_open
(req)¶ このメソッドは
BaseHandler
では定義されて いません 。しかし URL を開くための特定のハンドラが登録されていないような URL をキャッチしたいなら、サブクラスで定義する必要があります。このメソッドが定義されていた場合、
OpenerDirector
から呼び出されます。戻り値はdefault_open()
と同じでなければなりません。
-
BaseHandler.
http_error_default
(req, fp, code, msg, hdrs)¶ このメソッドは
BaseHandler
では定義されて いません 。しかしその他の処理されなかった HTTP エラーを処理する機能をもたせたいなら、サブクラスで定義する必要があります。このメソッドはエラーに遭遇したOpenerDirector
から自動的に呼び出されます。その他の状況では普通呼び出すべきではありません。req は
Request
オブジェクトで、 fp は HTTP エラー本体を読み出せるようなファイル類似のオブジェクトに なります。 code は 3 桁の 10 進数からなるエラーコードで、 msg ユーザ向けのエラーコード解説です。 hdrs は エラー応答のヘッダーをマップしたオブジェクトです。返される値および送出される例外は
urlopen()
と同じものでなければなりません。
-
BaseHandler.
http_error_nnn
(req, fp, code, msg, hdrs)¶ nnn は 3 桁の 10 進数からなる HTTP エラーコードでなくてはなりません。このメソッドも
BaseHandler
では定義されていませんが、サブクラスのインスタンスで定義されていた場合、エラーコード nnn の HTTP エラーが発生した際に呼び出されます。特定の HTTP エラーに対する処理を行うためには、このメソッドをサブクラスでオーバライドする必要があります。
引数、返される値、および送出される例外は
http_error_default()
と同じものでなければなりません。
-
BaseHandler.
protocol_request
(req) このメソッドは
BaseHandler
では 定義されていません が、サブクラスで特定のプロトコルのリクエストのプリプロセスを行いたい場合には定義する必要があります。このメソッドが定義されていると、親となる
OpenerDirector
から呼び出されます。その際、 req はRequest
オブジェクトになります。戻り値はRequest
オブジェクトでなければなりません。
-
BaseHandler.
protocol_response
(req, response) このメソッドは
BaseHandler
では 定義されていません が、サブクラスで特定のプロトコルのリクエストのポストプロセスを行いたい場合には定義する必要があります。このメソッドが定義されていると、親となる
OpenerDirector
から呼び出されます。その際、 req はRequest
オブジェクトになります。 response はurlopen()
の戻り値と同じインタフェースを 実装したオブジェクトになります。戻り値もまた、urlopen()
の戻り値と同じインタフェースを実装したオブジェクトでなければなりません。
21.6.4. HTTPRedirectHandler オブジェクト¶
注釈
一部の HTTP リクエストはこのモジュールのクライアントモードからの操作を要求します。その場合、HTTPError
が送出されます。さまざまなリダイレクションコードの正確な意味についての詳細は RFC 2616 を参照してください。
セキュリティ上の配慮として、HTTPRedirectHandler に HTTP、HTTPS、あるいは FTP の URL ではないリダイレクトされた URL が存在した場合、HTTPError
例外が送出されます。
-
HTTPRedirectHandler.
redirect_request
(req, fp, code, msg, hdrs, newurl)¶ リダイレクトへのレスポンスの
Request
またはNone
を返します。これはサーバーからリダイレクションを受信した時にhttp_error_30*()
メソッドのデフォルトの実装によって呼び出されます。リダイレクションを行わなければならない場合、newurl へのリダイレクトを実行するためのhttp_error_30*()
を許可する新しいRequest
を返します。その他の場合、この URL を扱うその他のハンドラーがない場合はHTTPError
を、他のハンドラーでできそうな場合はNone
を返します。
-
HTTPRedirectHandler.
http_error_301
(req, fp, code, msg, hdrs)¶ Location:
かURI:
のURL にリダイレクトします。このメソッドは HTTP における 'moved permanently' レスポンスを取得した際に 親オブジェクトとなるOpenerDirector
によって呼び出されます。
-
HTTPRedirectHandler.
http_error_302
(req, fp, code, msg, hdrs)¶ http_error_301()
と同じですが、'found' レスポンスに対して呼び出されます。
-
HTTPRedirectHandler.
http_error_303
(req, fp, code, msg, hdrs)¶ http_error_301()
と同じですが、'see other' レスポンスに対して呼び出されます。
-
HTTPRedirectHandler.
http_error_307
(req, fp, code, msg, hdrs)¶ http_error_301()
と同じですが、'temporary redirect' レスポンスに対して呼び出されます。
21.6.5. HTTPCookieProcessor オブジェクト¶
HTTPCookieProcessor
インスタンスは属性をひとつだけ持ちます:
Cookie の入っている
http.cookiejar.CookieJar
オブジェクトです。
21.6.6. ProxyHandler オブジェクト¶
-
ProxyHandler.
protocol_open
(request) ProxyHandler
は、コンストラクターで与えた辞書 proxies にプロキシが設定されているような protocol すべてについて、メソッドprotocol_open()
を持つことになります。このメソッドはrequest.set_proxy()
を呼び出して、リクエストがプロキシを通過できるように修正します。その後連鎖するハンドラーの中から次のハンドラーを呼び出して実際にプロトコルを実行します。
21.6.7. HTTPPasswordMgr オブジェクト¶
以下のメソッドは HTTPPasswordMgr
および HTTPPasswordMgrWithDefaultRealm
オブジェクトで利用できます。
-
HTTPPasswordMgr.
add_password
(realm, uri, user, passwd)¶ uri は単一の URI でも複数の URI からなるシーケンスでもかまいません。 realm 、 user および passwd は文字列でなくてはなりません。このメソッドによって、 realm と与えられた URI の上位 URI に対して
(user, passwd)
が認証トークンとして使われるようになります。
-
HTTPPasswordMgr.
find_user_password
(realm, authuri)¶ 与えられたレルムおよび URI に対するユーザ名またはパスワードがあればそれを取得します。該当するユーザ名/パスワードが存在しない場合、このメソッドは
(None, None)
を返します。HTTPPasswordMgrWithDefaultRealm
オブジェクトでは、与えられた realm に対して該当するユーザ名/パスワードが存在しない場合、レルムNone
が検索されます。
21.6.8. HTTPPasswordMgrWithPriorAuth オブジェクト¶
このパスワードマネージャは HTTPPasswordMgrWithDefaultRealm
を継承して、認証の証明書を常に送らないといけない 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 は無視されます。
-
HTTPPasswordMgr.
find_user_password
(realm, authuri) HTTPPasswordMgrWithDefaultRealm
オブジェクトに対する同名のメソッドと同じです。
-
HTTPPasswordMgrWithPriorAuth.
update_authenticated
(self, uri, is_authenticated=False)¶ 与えられた url や URI のリストの
is_authenticated
フラグを更新します。
-
HTTPPasswordMgrWithPriorAuth.
is_authenticated
(self, authuri)¶ 与えられた URI の
is_authenticated
フラグの現在の状態を返します。
21.6.9. AbstractBasicAuthHandler オブジェクト¶
-
AbstractBasicAuthHandler.
http_error_auth_reqed
(authreq, host, req, headers)¶ ユーザ名/パスワードを取得し、再度サーバへのリクエストを試みることで、サーバからの認証リクエストを処理します。 authreq はリクエストにおいて レルムに関する情報が含まれているヘッダーの名前、 host は認証を行う対象の URL とパスを指定します、 req は (失敗した)
Request
オブジェクト、そして headers はエラーヘッダーでなくてはなりません。host は、オーソリティ (例
"python.org"
) か、オーソリティコンポーネントを含む URL (例"http://python.org"
) です。どちらの場合も、オーソリティはユーザ情報コンポーネントを含んではいけません (なので、"python.org"
や"python.org:80"
は正しく、"joe:password@python.org"
は不正です) 。
21.6.10. HTTPBasicAuthHandler オブジェクト¶
-
HTTPBasicAuthHandler.
http_error_401
(req, fp, code, msg, hdrs)¶ 認証情報がある場合、認証情報付きで再度リクエストを試みます。
21.6.11. ProxyBasicAuthHandler オブジェクト¶
-
ProxyBasicAuthHandler.
http_error_407
(req, fp, code, msg, hdrs)¶ 認証情報がある場合、認証情報付きで再度リクエストを試みます。
21.6.12. AbstractDigestAuthHandler オブジェクト¶
21.6.13. HTTPDigestAuthHandler オブジェクト¶
-
HTTPDigestAuthHandler.
http_error_401
(req, fp, code, msg, hdrs)¶ 認証情報がある場合、認証情報付きで再度リクエストを試みます。
21.6.14. ProxyDigestAuthHandler オブジェクト¶
-
ProxyDigestAuthHandler.
http_error_407
(req, fp, code, msg, hdrs)¶ 認証情報がある場合、認証情報付きで再度リクエストを試みます。
21.6.15. HTTPHandler オブジェクト¶
-
HTTPHandler.
http_open
(req)¶ HTTP リクエストを送ります。
req.has_data()
に応じて、 GET または POST のどちらでも送ることができます。
21.6.16. HTTPSHandler オブジェクト¶
-
HTTPSHandler.
https_open
(req)¶ HTTPS リクエストを送ります。
req.has_data()
に応じて、 GET または POST のどちらでも送ることができます。
21.6.17. FileHandler オブジェクト¶
21.6.18. DataHandler オブジェクト¶
-
DataHandler.
data_open
(req)¶ Read a data URL. This kind of URL contains the content encoded in the URL itself. The data URL syntax is specified in RFC 2397. This implementation ignores white spaces in base64 encoded data URLs so the URL may be wrapped in whatever source file it comes from. But even though some browsers don't mind about a missing padding at the end of a base64 encoded data URL, this implementation will raise an
ValueError
in that case.
21.6.19. FTPHandler オブジェクト¶
-
FTPHandler.
ftp_open
(req)¶ req で表されるファイルを FTP 越しにオープンします。ログインは常に空のユーザネームおよびパスワードで行われます。
21.6.20. CacheFTPHandler オブジェクト¶
CacheFTPHandler
オブジェクトは FTPHandler
オブジェクトに以下のメソッドを追加したものです:
-
CacheFTPHandler.
setTimeout
(t)¶ 接続のタイムアウトを t 秒に設定します。
-
CacheFTPHandler.
setMaxConns
(m)¶ キャッシュ付き接続の最大接続数を m に設定します。
21.6.22. HTTPErrorProcessor オブジェクト¶
-
HTTPErrorProcessor.
http_response
(request, response)¶ HTTP エラー応答の処理をします。
エラーコード 200 の場合、レスポンスオブジェクトを即座に返します。
200 以外のエラーコードの場合、これは単に
protocol_error_code()
ハンドラーメソッドにOpenerDirector.error()
経由で処理を渡します。他にそのエラーを処理するハンドラーがない場合、HTTPDefaultErrorHandler
は最後にHTTPError
を送出します。
-
HTTPErrorProcessor.
https_response
(request, response)¶ HTTPS エラー応答の処理をします。
振る舞いは
http_response()
と同じです。
21.6.23. 使用例¶
以下の例の他に urllib パッケージを使ってインターネット上のリソースを取得するには に多くの例があります。
以下の例では、python.org のメインページを取得して、その最初の 300 バイト分を表示します。
>>> 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 は bytes オブジェクトを返すことに注意してください。これは urlopen が、HTTP サーバーから受信したバイトストリームのエンコーディングを自動的に決定できないためです。一般に、返された bytes オブジェクトを文字列にデコードするためのエンコーディングの決定あるいは推測はプログラム側が行います。
以下の W3C ドキュメント https://www.w3.org/International/O-charsetには (X)HTML や XML ドキュメントでそのエンコーディング情報を指定するさまざまな方法の一覧があります。
python.org ウェブサイトでは utf-8 エンコーディングを使用しており、それをその meta タグで指定していますので、bytes オブジェクトのデコードも同様に行います。
>>> 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
コンテキストマネージャー を使用しないアプローチでも同様の結果を得ることができます。
>>> 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
以下の例では、データストリームを CGI の標準入力へ送信し、返されたデータを読み込みます。この例は Python が SSL をサポートするように設定してインストールされている場合のみ動作します。
>>> 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
を使った 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()
はデフォルトで沢山のハンドラを提供しており、その中に ProxyHandler
があります。デフォルトでは、 ProxyHandler
は <scheme>_proxy
という環境変数を使います。 ここで <scheme>
は URL スキームです。例えば、 HTTP プロキシの URL を得るには、環境変数 http_proxy
を読み出します。
この例では、デフォルトの ProxyHandler
を置き換えてプログラム的に作成したプロキシ 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 ヘッダーを追加する例です:
headers 引数を使って Request
コンストラクタを呼び出す方法の他に、以下のようにできます:
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
メソッドを使ってパラメータを含む 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 から出力されたパラメーターは urlopen にデータとして渡される前に bytes にエンコードされていることに注意してください:
>>> 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 プロキシを明示的に設定しています:
>>> 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')
...
以下の例では、環境変数による設定内容に対して上書きする形で、まったくプロキシを使わないよう設定しています:
>>> import urllib.request
>>> opener = urllib.request.FancyURLopener({})
>>> with opener.open("http://www.python.org/") as f:
... f.read().decode('utf-8')
...
21.6.24. レガシーインターフェース¶
以下の関数およびクラスは、Python 2 のモジュール urllib
(urllib2
ではありません) から移植されたものです。これらは将来的に廃止されるかもしれません。
-
urllib.request.
urlretrieve
(url, filename=None, reporthook=None, data=None)¶ URL で表されるネットワークオブジェクトをローカルファイルにコピーします。 URL がローカルファイルを示している場合は、ファイル名が与えられない限りオブジェクトはコピーされません。戻り値はタプル
(filename, headers)
になり、 filename はオブジェクトが保存されたローカルファイル名、 headers は (リモートオブジェクトに対しては)urlopen()
が返したオブジェクトのinfo()
メソッドが返すものすべてになります。例外はurlopen()
のものと同じになります。The second argument, if present, specifies the file location to copy to (if absent, the location will be a tempfile with a generated name). The third argument, if present, is a callable that will be called once on establishment of the network connection and once after each block read thereafter. The callable will be passed three arguments; a count of blocks transferred so far, a block size in bytes, and the total size of the file. The third argument may be
-1
on older FTP servers which do not return a file size in response to a retrieval request.以下は最も一般的な使用例です:
>>> import urllib.request >>> local_filename, headers = urllib.request.urlretrieve('http://python.org/') >>> html = open(local_filename) >>> html.close()
url が
http:
スキーム識別子を使用していた場合、任意の引数 data はPOST
リクエストの指定に使用される場合があります (通常のリクエストタイプはGET
です)。引数 data は標準 application/x-www-form-urlencoded 形式のバイトオブジェクトでなければなりません。urllib.parse.urlencode()
関数を参照してください。urlretrieve()
は、予想 (これは Content-Length ヘッダーにより通知されるサイズです) よりも取得できるデータ量が少ないことを検知した場合、ContentTooShortError
を発生します。これは、例えば、ダウンロードが中断された場合などに発生します。Content-Length はデータ量の下限です: 読み込むデータ量がこれを超えている場合 urlretrieve はそれらも読み込みますが、利用できるデータがこれを下回った場合、例外が送出されます。
このような場合にもダウンロードされたデータを取得することは可能で、これは exception インスタンスの
content
属性に保存されています。Content-Length ヘッダーが与えられなれけば urlretrieve はダウンロードしたデータのサイズをチェックできません。この場合ダウンロードは正常に完了したとみなすしかありません。
-
urllib.request.
urlcleanup
()¶ 以前の
urlretrieve()
呼び出し後に残っているかもしれない一時ファイルをクリーンアップします。
-
class
urllib.request.
URLopener
(proxies=None, **x509)¶ バージョン 3.3 で非推奨.
URL をオープンし、読み出すためのクラスの基底クラスです。
http:
,ftp:
,file:
以外のスキームを使ったオブジェクトのオープンをサポートしたいのでないかぎり、FancyURLopener
を使おうと思うことになるでしょう。デフォルトでは、
URLopener
クラスは User-Agent ヘッダーとしてurllib/VVV
を送信します。ここで VVV はurllib
のバージョン番号です。アプリケーションで独自の User-Agent ヘッダーを送信したい場合は、URLopener
かまたはFancyURLopener
のサブクラスを作成し、サブクラス定義においてクラス属性version
を適切な文字列値に設定することで行うことができます。オプションのパラメーター proxies はスキーム名をプロキシの URL にマップする辞書でなければなりません。空の辞書はプロキシ機能を完全にオフにします。デフォルトの値は
None
で、この場合、urlopen()
の定義で述べたように、プロキシを設定する環境変数が存在するならそれを使います。追加のキーワードパラメーターは x509 に集められますが、これは
https:
スキームを使った際のクライアント認証に使われることがあります。キーワード引数 key_file および cert_file が SSL 鍵と証明書を設定するためにサポートされています; クライアント認証をするには両方が必要です。URLopener
オブジェクトはサーバーがエラーコードを返した場合にOSError
例外を送出します。-
open
(fullurl, data=None)¶ 適切なプロトコルを使って fullurl を開きます。このメソッドはキャッシュとプロキシ情報を設定し、その後適切な open メソッドを入力引数つきで呼び出します。認識できないスキームが与えられた場合、
open_unknown()
が呼び出されます。 data 引数はurlopen()
の引数 data と同じ意味を持っています。
-
open_unknown
(fullurl, data=None)¶ オーバライド可能な、未知のタイプの URL を開くためのインタフェースです。
-
retrieve
(url, filename=None, reporthook=None, data=None)¶ url の内容を取得し、filename に保存します。戻り値は、ローカルファイル名と、レスポンスヘッダーが含まれる
email.message.Message
(リモート URL の場合) かNone
(ローカル URL の場合) からなるタプルになります。呼び出し側は、その後 filename を開いてその内容を読み込まなければなりません。filename が与えられず、URL がローカルファイルを参照している場合、入力ファイル名が返されます。URL がローカルでなく、filename が与えられていない場合、ファイル名は入力 URL のパスの最後の構成要素のサフィックスとマッチするサフィックスを持つtempfile.mktemp()
の出力になります。reporthook が与えられている場合、3 つの数値 (チャンク数、読み込んだチャンクの最大サイズ、および総ダウンロードサイズ --- 不明の場合は -1) の引数を受け取る関数でなければなりません。これは開始時に 1 回と、ネットワークからデータのチャンクを読み込む度に呼び出されます。reporthook はローカル URL に対しては無視されます。url が
http:
スキーム識別子を使用していた場合、任意の引数 data はPOST
リクエストの指定に使用される場合があります (通常のリクエストタイプはGET
です)。引数 data は標準 application/x-www-form-urlencoded 形式でなければなりません。urllib.parse.urlencode()
関数を参照してください。
-
-
class
urllib.request.
FancyURLopener
(...)¶ バージョン 3.3 で非推奨.
FancyURLopener
はURLopener
のサブクラスで、以下の HTTP レスポンスコード: 301、302、303、 307、および 401 を取り扱う機能を提供します。レスポンスコード 30x に対しては、 Location ヘッダーを使って実際の URL を取得します。レスポンスコード 401 (認証が要求されていることを示す) に対しては、BASIC認証 (basic HTTP authintication) が行われます。レスポンスコード 30x に対しては、最大で maxtries 属性に指定された数だけ再帰呼び出しを行うようになっています。この値はデフォルトで 10 です。その他のレスポンスコードについては、
http_error_default()
が呼ばれます。これはサブクラスでエラーを適切に処理するようにオーバーライドすることができます。注釈
RFC 2616 によると、 POST 要求に対する 301 および 302 応答はユーザの承認無しに自動的にリダイレクトしてはなりません。実際は、これらの応答に対して自動リダイレクトを許すブラウザでは POST を GET に変更しており、
urllib
でもこの動作を再現します。コンストラクタに与えるパラメーターは
URLopener
と同じです。注釈
基本的な HTTP 認証を行う際、
FancyURLopener
インスタンスはprompt_user_passwd()
メソッドを呼び出します。このメソッドはデフォルトでは実行を制御している端末上で認証に必要な情報を要求するように実装されています。必要ならば、このクラスのサブクラスにおいてより適切な動作をサポートするためにprompt_user_passwd()
メソッドをオーバライドしてもかまいません。FancyURLopener
クラスはオーバライド可能な追加のメソッドを提供しており、適切な振る舞いをさせることができます:-
prompt_user_passwd
(host, realm)¶ 指定されたセキュリティ領域 (security realm) 下にある与えられたホストにおいて、ユーザー認証に必要な情報を返すための関数です。この関数が返す値は
(user, password)
からなるタプルでなければなりません。値は Basic 認証で使われます。このクラスでの実装では、端末に情報を入力するようプロンプトを出します; ローカルの環境において適切な形で対話型モデルを使うには、このメソッドをオーバライドしなければなりません。
-
21.6.25. urllib.request
の制限事項¶
現在、次のプロトコルのみサポートされています: HTTP (バージョン 0.9 および 1.0)、FTP、ローカルファイル、およびデータ URL
バージョン 3.4 で変更: データ URL サポートが追加されました。
urlretrieve()
のキャッシュ機能は、誰かが Expiration time ヘッダーの正しい処理をハックする時間を見つけるまで無効にされています。ある URL がキャッシュにあるかどうか調べるような関数があればと思っています。
後方互換性のため、 URL がローカルシステム上のファイルを指しているように見えるにも関わらずファイルを開くことができなければ、 URL は FTP プロトコルを使って再解釈されます。この機能は時として混乱を招くエラーメッセージを引き起こします。
関数
urlopen()
およびurlretrieve()
は、ネットワーク接続が確立されるまでの間、一定でない長さの遅延を引き起こすことがあります。このことは、これらの関数を使ってインタラクティブな Web クライアントを構築するのはスレッドなしには難しいことを意味します。urlopen()
あるいはurlretrieve()
が返すデータはサーバーから返された生データです。これは (画像のような) バイナリ、プレーンテキスト、あるいは (例えば) HTML などになります。HTTP プロトコルはレスポンスヘッダー内でタイプ情報を提供しており、Content-Type ヘッダーを見ることで調査できます。返されたデータが HTML の場合、モジュールhtml.parser
を使用してこれを解析できます。FTP プロトコルを扱うコードでは、ファイルとディレクトリを区別できません。このことから、アクセスできないファイルを指している URL からデータを読み出そうとすると、予期しない動作を引き起こす場合があります。 URL が
/
で終わっていれば、ディレクトリを指しているものとみなして、それに適した処理を行います。しかし、ファイルの読み出し操作が 550 エラー (URL が存在しないか、主にパーミッションの理由でアクセスできない) になった場合、 URL がディレクトリを指していて、末尾の/
を忘れたケースを処理するため、パスをディレクトリとして扱います。このために、パーミッションのためにアクセスできないファイルを fetch しようとすると、FTP コードはそのファイルを開こうとして 550 エラーに陥り、次にディレクトリ一覧を表示しようとするため、誤解を生むような結果を引き起こす可能性があるのです。よく調整された制御が必要なら、ftplib
モジュールを使うか、FancyURLopener
をサブクラス化するか、 _urlopener を変更して目的に合わせるよう検討してください。
21.7. urllib.response
--- urllib で使用するレスポンスクラス¶
urllib.response
モジュールは、read()
および readline()
を含む 最小限のファイルライクインターフェースを定義する関数およびクラスを定義しています。代表的なレスポンスオブジェクトは addinfourl インスタンスで、レスポンスヘッダーを返す info()
メソッドおよび URL を返す geturl()
メソッドを定義しています。このモジュールで定義された関数は、urllib.request
モジュール内で使用されます。