`urllib.request` --- URL を開くための拡張可能なライブラリ¶

urllib.request モジュールは、Basic 認証や Digest 認証、リダイレクト、Cookie などが絡む複雑な状況で URL (主に HTTP) を開くための関数とクラスを定義しています。

参考

より高水準のHTTPクライアントインターフェースとして Requestsパッケージがお奨めです。

警告

macOS 向けの getproxies() の実装は高水準のシステム API を使うため、macOS で os.fork() を使うプログラムからこのモジュールを利用するのは安全ではありません。この問題を避けるには、環境変数 no_proxy を * に設定してください (例: os.environ["no_proxy"] = "*")。

利用可能な環境: not WASI.

このモジュールは WebAssembly では動作しないか、利用不可です。詳しくは、WebAssembly プラットフォームを見てください。

urllib.request モジュールは以下の関数を定義しています:

urllib.request.urlopen(url, data=None, [timeout, ]*, 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 を参照してください。

この関数は常にプロパティ url、 headers、および status を持ち、コンテキストマネージャとして動作するオブジェクトを返します。これらのプロパティに関する詳細は urllib.response.addinfourl を確認してください。

HTTP および HTTPS URL の場合、この関数は、わずかに修正された http.client.HTTPResponse オブジェクトを返します。上記の3つの新しいメソッドに加えて、 msg 属性が HTTPResponse のドキュメンテーションで指定されているレスポンスヘッダーの代わりに reason 属性 --- サーバーから返された reason フレーズ --- と同じ情報を含んでいます。

FTP 、ファイルおよびデータURLの場合、この関数は urllib.response.addinfourl オブジェクトを返します。

プロトコルエラー発生時は URLError を送出します。

どのハンドラもリクエストを処理しなかった場合には None を返すことがあるので注意してください (デフォルトでインストールされるグローバルハンドラの OpenerDirector は、 UnknownHandler を使って上記の問題が起きないようにしています)。

さらに、プロキシ設定が検出された場合(例えば http_proxy のような *_proxy 環境変数がセットされているなど)には ProxyHandler がデフォルトでインストールされ、これがプロキシを通してリクエストを処理するようにしています。

Python 2.6 以前のレガシーな urllib.urlopen 関数は廃止されました。urllib.request.urlopen() が過去の urllib2.urlopen に相当します。urllib.urlopen において辞書型オブジェクトで渡していたプロキシの扱いは、ProxyHandler オブジェクトを使用して取得できます。

デフォルトの opener は、リクエストオブジェクトから取得した引数 fullurl、data、headers、method とともに、監査イベント urllib.Request を発生させます。

バージョン 3.2 で変更: cafile および capath が追加されました。

HTTPS バーチャルホストがサポートされました (ssl.HAS_SNI が真の場合のみ)。

data にイテラブルなオブジェクトを指定できるようになりました。

バージョン 3.3 で変更: cadefault が追加されました。

バージョン 3.4.3 で変更: context が追加されました。

バージョン 3.10 で変更: context が指定されていない場合、HTTPS 接続でプロトコル識別子 http/1.1 を含む ALPN 拡張を送信するようになりました。独自の context を指定する場合は、set_alpn_protocols() で ALPN プロトコルを設定してください。

バージョン 3.13 で変更: cafile、capath、cadefault パラメータが削除されました。代わりに context パラメータを使ってください。

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, *, add_scheme=False)¶

指定されたローカルパスを file: URL に変換します。この関数は quote() を使ってパスをエンコードします。

add_scheme が偽 (デフォルト) の場合、戻り値から file: スキームの接頭辞を省きます。完全な URL を返すには add_scheme を真に設定してください。

次は Windows でこの関数を使う例です。

>>> from urllib.request import pathname2url
>>> path = 'C:\\Program Files'
>>> pathname2url(path, add_scheme=True)
'file:///C:/Program%20Files'

バージョン 3.14 で変更: Windows のドライブ文字を大文字に変換しなくなりました。また、Windows でドライブ文字の直後以外にある : に対して OSError を送出しなくなりました。

バージョン 3.14 で変更: スラッシュで始まるパスは authority 部を持つ URL に変換されます。例えば、パス /etc/hosts は URL ///etc/hosts に変換されます。

バージョン 3.14 で変更: add_scheme パラメータが追加されました。

urllib.request.url2pathname(url, *, require_scheme=False, resolve_host=False)¶

指定された file: URL をローカルパスに変換します。この関数は unquote() を使って URL をデコードします。

require_scheme が偽 (デフォルト) の場合、渡す値から file: スキームの接頭辞を省いてください。 require_scheme を真に設定した場合は、渡す値にこの接頭辞を含めてください。含まれていないと URLError を送出します。

URL の authority が空、localhost、またはローカルホスト名の場合は、authority を取り除きます。それ以外の場合、resolve_host を真に設定すると socket.gethostbyname() で authority を名前解決し、ローカルの IP アドレスと一致すれば取り除きます (RFC 8089 §3 に従います)。それでも authority が処理されなかった場合、Windows では UNC パスを返し、他のプラットフォームでは URLError を送出します。

次は Windows でこの関数を使う例です。

>>> from urllib.request import url2pathname
>>> url = 'file:///C:/Program%20Files'
>>> url2pathname(url, require_scheme=True)
'C:\\Program Files'

バージョン 3.14 で変更: Windows のドライブ文字を大文字に変換しなくなりました。また、Windows でドライブ文字の直後以外にある : に対して OSError を送出しなくなりました。

バージョン 3.14 で変更: URL の authority がローカルホスト名と一致する場合は、authority を取り除くようになりました。一致せず、authority が空でも localhost でもない場合は、Windows では従来どおり UNC パスを返し、他のプラットフォームでは URLError を送出します。

バージョン 3.14 で変更: URL にクエリやフラグメント要素がある場合は、取り除くようになりました。

バージョン 3.14 で変更: require_scheme および resolve_host パラメータが追加されました。

urllib.request.getproxies()¶: このヘルパー関数はスキーマからプロキシサーバーのURLへのマッピングを行う辞書を返します。この関数はまず、どのOSでも最初に <scheme>_proxy という名前の環境変数を大文字小文字を区別せずにスキャンします。そこで見つからなかった場合、 macOS の場合は macOS システム環境設定を、 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 はサーバーに送信する追加データを指定するオブジェクト、追加データが不要な場合は None でなければなりません。現在、data を使うのは HTTP リクエストだけです。サポートされるオブジェクトの型には、bytes、ファイルライクオブジェクト、バイト列類似オブジェクトのイテラブルがあります。 Content-Length ヘッダーフィールドも Transfer-Encoding ヘッダーフィールドも指定されていない場合、HTTPHandler は data の型に応じてこれらのヘッダーを設定します。 bytes オブジェクトの送信には Content-Length を使い、ファイルやその他のイテラブルの送信には RFC 7230 の 3.3.1 節で規定された Transfer-Encoding: chunked を使います。

HTTP POST リクエストメソッドでは data は標準の application/x-www-form-urlencoded 形式のバッファーでなければなりません。 urllib.parse.urlencode() 関数は、マップ型あるいは 2 タプルのシーケンスを取り、この形式の ASCII 文字列を返します。これは data パラメーターとして使用される前に bytes 型にエンコードされなければなりません。

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の場合) と設定します。headersのすべてのキーはキャメルケースで送信されます。

data 引数がある場合は、適切な Content-Type ヘッダーを含めてください。このヘッダーが指定されておらず、data が None でない場合、デフォルトで Content-Type: application/x-www-form-urlencoded が追加されます。

次の2つの引数は、サードパーティの 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 は使用される HTTP リクエストメソッド (例: 'HEAD') を示す文字列でなければなりません。もし与えられた場合、この値は属性 method に格納され、 get_method() で使用されます。デフォルトは data が None であれば 'GET' で、そうでなければ 'POST' です。サブクラスは method 属性をクラス自身に設定して、異なるデフォルトメソッドを示すことができます。

注釈

データオブジェクトが内容を複数回提供できない場合 (ファイルや、一度しか内容を生成できないイテラブルなど)、HTTP リダイレクトや認証のためにリクエストを再試行すると、期待どおりに動作しません。 data はヘッダーの直後に HTTP サーバーに送られます。このライブラリは 100-continue による待機をサポートしていません。

バージョン 3.3 で変更: 引数 Request.method が Request クラスに追加されました。

バージョン 3.4 で変更: Request.method のデフォルト値はクラスレベルで指定されることがあります。

バージョン 3.6 で変更: Content-Length が指定されておらず、data が None でも bytes オブジェクトでもない場合に、エラーを送出しなくなりました。代わりにチャンク転送エンコーディングを使います。

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 環境では、レジストリのインターネット設定セクションからプロキシ設定を手に入れ、 macOS 環境では、 macOS システム設定フレームワーク (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 ハンドラによって使われます。

Added in version 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 が呼ばれます。

Added in version 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 オブジェクトを参照してください。

バージョン 3.14 で変更: HTTP Digest 認証の SHA-256 アルゴリズムをサポートしました。

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 を開きます。

Added in version 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 エラー応答の処理をします。

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.selector¶: URI パスです。Request がプロキシを使用する場合、セレクターはプロキシに渡される完全な URL になります。

Request.data¶: リクエストのエンティティボディか、指定されない場合は None になります。

バージョン 3.4 で変更: Request.data の値が変更されると、もしそれ以前に "Content-Length" ヘッダーの値が設定または計算されていたらヘッダーが削除されるようになりました。

Request.unverifiable¶: リクエストが RFC 2965 で定義された証明不能 (unverifiable) であるかどうかを示す論理値です。

Request.method¶: HTTP リクエストで使うメソッドです。デフォルト値は None で、このときは使うメソッドを get_method() が通常の方法で決定するということになります。この値を設定する (従って get_method() のデフォルトの決定を上書きする) 方法は、 Request サブクラスでのクラスレベルの設定処理でデフォルト値を提供するか、 Request のコンストラクタの method 引数へ値を渡すかです。

Added in version 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)¶: リクエストインスタンス (の通常のヘッダーと非リダイレクトヘッダーの両方) から名前つきヘッダーを削除します。

Added in version 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 が削除されました。

OpenerDirector オブジェクト¶

OpenerDirector インスタンスは以下のメソッドを持っています:

OpenerDirector.add_handler(handler)¶

handler は BaseHandler のインスタンスでなければなりません。次のメソッドを探し、対応するハンドラーの連鎖に追加します (HTTP エラーは特別扱いされることに注意してください)。以下の protocol は処理対象の実際のプロトコルに置き換えてください。例えば http_response() は HTTP プロトコルのレスポンスハンドラーになります。また、type は実際の HTTP コードに置き換えてください。例えば http_error_404() は HTTP 404 エラーを処理します。

<protocol>_open() --- ハンドラーが protocol の URL を開く方法を知っていることを示します。

詳細は、 BaseHandler.<protocol>_open() を参照してください。
http_error_<type>() --- ハンドラーが HTTP エラーコード type の処理方法を知っていることを示すシグナルです。

詳細は、 BaseHandler.http_error_<nnn>() を参照してください。
<protocol>_error() --- ハンドラーが (http でない) protocol のエラーを処理する方法を知っていることを示すシグナルです。
<protocol>_request() --- ハンドラーが protocol リクエストのプリプロセス方法を知っていることを示すシグナルです。

詳細は、 BaseHandler.<protocol>_request() を参照してください。
<protocol>_response() --- ハンドラーが protocol レスポンスのポストプロセス方法を知っていることを示すシグナルです。

詳細は、 BaseHandler.<protocol>_response() を参照してください。

OpenerDirector.open(url, data=None[, timeout])¶: 与えられた url (リクエストオブジェクトでも文字列でもかまいません) を開きます。オプションとして data を与えることができます。引数、戻り値、および送出される例外は urlopen() と同じです (urlopen() の場合、標準でインストールされているグローバルな OpenerDirector の open() メソッドを呼び出します) 。オプションの timeout 引数は、接続開始のようなブロックする処理におけるタイムアウト時間を秒数で指定します。(指定しなかった場合は、グローバルのデフォルト設定が利用されます) タイムアウト機能は、 HTTP, HTTPS, FTP 接続でのみ有効です。

OpenerDirector.error(proto, *args)¶

与えられたプロトコルにおけるエラーを処理します。このメソッドは与えられたプロトコルにおける登録済みのエラーハンドラを (プロトコル固有の) 引数で呼び出します。 HTTP プロトコルは特殊なケースで、特定のエラーハンドラを選び出すのに HTTP レスポンスコードを使います; ハンドラクラスの http_error_<type>() メソッドを参照してください。

戻り値および送出される例外は urlopen() と同じものです。

OpenerDirector オブジェクトは、以下の 3 つのステージに分けて URL を開きます:

各ステージでこれらのメソッドを呼び出す順序は、ハンドラーのインスタンスをソートして決めます。

<protocol>_request() 形式のメソッドを持つすべてのハンドラーに対してそのメソッドを呼び出し、リクエストのプリプロセスを行います。
<protocol>_open() のような名前のメソッドを持つハンドラーが呼び出され、リクエストを処理します。このステージは、ハンドラーが None 以外の値 (つまりレスポンス) を返すか、例外 (通常は URLError) を送出すると終了します。例外はそのまま伝播します。

実際には、上のアルゴリズムではまず default_open() という名前のメソッドを呼び出します。このメソッドがすべて None を返す場合、同じアルゴリズムを繰り返して、今度は <protocol>_open() 形式のメソッドを試します。メソッドがすべて None を返すと、さらに同じアルゴリズムを繰り返して unknown_open() を呼び出します。

これらのメソッドの実装には、親となる OpenerDirector インスタンスの open() や error() といったメソッド呼び出しが入る場合があるので注意してください。
<protocol>_response() 形式のメソッドを持つすべてのハンドラーに対してそのメソッドを呼び出し、レスポンスのポストプロセスを行います。

BaseHandler オブジェクト¶

BaseHandler オブジェクトは直接的に役に立つ 2 つのメソッドと、その他として派生クラスで使われることを想定したメソッドを提供します。以下は直接的に使うためのメソッドです:

BaseHandler.add_parent(director)¶: 親オブジェクトとして、 director を追加します。

BaseHandler.close()¶: 全ての親オブジェクトを削除します。

以下の属性とメソッドは、BaseHandler から派生したクラスでのみ使うべきです。

注釈

慣習的に、 <protocol>_request() や <protocol>_response() といったメソッドを定義しているサブクラスは *Processor`と名づけ、その他は :class:!*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 をキャッチしたいなら、サブクラスで定義する必要があります。

このメソッドが定義されていた場合、 parent OpenerDirector から呼び出されます。戻り値は default_open() と同じでなければなりません。

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

このメソッドは BaseHandler では定義されて いません 。しかしその他の処理されなかった HTTP エラーを処理する機能をもたせたいなら、サブクラスで定義する必要があります。このメソッドはエラーに遭遇した OpenerDirector から自動的に呼び出されます。その他の状況では普通呼び出すべきではありません。

OpenerDirector は五つの位置引数を渡してこのメソッドを呼び出します:

Request オブジェクト
HTTP エラーの本文を含むファイルライクオブジェクト
the three-digit code of the error, as a string,
利用者向けのコードの説明を表す文字列
エラーのヘッダーを表すマッピングオブジェクト

返される値および送出される例外は 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() の戻り値と同じインターフェースを実装したオブジェクトでなければなりません。

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*() メソッドのデフォルトの実装がこのメソッドを呼び出します。リダイレクトを行う場合は、http_error_30*() が newurl へのリダイレクトを実行できるように、新しい Request を返します。それ以外の場合、この URL をほかのハンドラーに処理させるべきでなければ HTTPError を送出し、このハンドラーでは処理できなくてもほかのハンドラーなら処理できる可能性があれば None を返します。

注釈

このメソッドのデフォルトの実装は、 RFC 2616 に厳密に従ったものではありません。 RFC 2616 では、 POST リクエストに対する 301 および 302 応答が、ユーザの承認なく自動的にリダイレクトされてはならないと述べています。現実には、ブラウザは POST を GET に変更することで、これらの応答に対して自動的にリダイレクトを行えるようにしています。デフォルトの実装でも、この挙動を再現しています。

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' レスポンスに対して呼び出されます。リクエストメソッドを POST から GET に変更することは認めません。

HTTPRedirectHandler.http_error_308(req, fp, code, msg, hdrs)¶: http_error_301() と同じですが、'permanent redirect' レスポンスに対して呼び出されます。リクエストメソッドを POST から GET に変更することは認めません。

Added in version 3.11.

HTTPCookieProcessor オブジェクト¶

HTTPCookieProcessor インスタンスは属性をひとつだけ持ちます:

HTTPCookieProcessor.cookiejar¶: Cookie の入っている http.cookiejar.CookieJar オブジェクトです。

ProxyHandler オブジェクト¶

ProxyHandler.<protocol>_open(request): ProxyHandler は、コンストラクターで与えた辞書 proxies にプロキシが設定されているような protocol すべてについて、メソッド <protocol>_open() を持つことになります。このメソッドは request.set_proxy() を呼び出して、リクエストがプロキシを通過できるように修正します。その後連鎖するハンドラーの中から次のハンドラーを呼び出して実際にプロトコルを実行します。

HTTPPasswordMgr オブジェクト¶

以下のメソッドは HTTPPasswordMgr および HTTPPasswordMgrWithDefaultRealm オブジェクトで利用できます。

HTTPPasswordMgr.add_password(realm, uri, user, passwd)¶: uri can be either a single URI, or a sequence of URIs. realm, user and passwd must be strings. This causes (user, passwd) to be used as authentication tokens when authentication for realm and a super-URI of any of the given URIs is given. If a URI includes a scheme, its credentials only match authentication URIs with the same scheme or no scheme. A URI without a scheme matches authentication URIs with any scheme.

バージョン 3.15 で変更: スキームを含む URI の認証情報は、そのスキームの範囲に限定されるようになりました。

HTTPPasswordMgr.find_user_password(realm, authuri)¶

与えられたレルムおよび URI に対するユーザ名またはパスワードがあればそれを取得します。該当するユーザ名／パスワードが存在しない場合、このメソッドは (None, None) を返します。

HTTPPasswordMgrWithDefaultRealm オブジェクトでは、与えられた realm に対して該当するユーザ名/パスワードが存在しない場合、レルム None が検索されます。

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 は無視されます。

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 フラグの現在の状態を返します。

AbstractBasicAuthHandler オブジェクト¶

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

ユーザ名／パスワードを取得し、再度サーバへのリクエストを試みることで、サーバからの認証リクエストを処理します。 authreq はリクエストにおいてレルムに関する情報が含まれているヘッダーの名前、 host は認証を行う対象の URL とパスを指定します、 req は (失敗した) Request オブジェクト、そして headers はエラーヘッダーでなくてはなりません。

headers は、email.message.Message や wsgiref.headers.Headers のように、大文字と小文字を区別せずに検索でき、get_all() メソッドを実装するマッピングに似たオブジェクトでなければなりません。

host は authority (例: "python.org") または authority 要素を含む URL (例: "https://python.org/") です。いずれの場合も、authority に userinfo 要素を含めてはなりません ("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 はリクエストにおいてレルムに関する情報が含まれているヘッダーの名前、 host は認証を行う対象のホスト名、 req は (失敗した) Request オブジェクト、そして headers はエラーヘッダーでなくてはなりません。

headers は、email.message.Message や wsgiref.headers.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)¶: HTTP リクエストを送ります。 req.data に応じて、 GET または POST のどちらでも送ることができます。

HTTPSHandler オブジェクト¶

HTTPSHandler.https_open(req)¶: HTTPS リクエストを送ります。 req.data に応じて、 GET または POST のどちらでも送ることができます。

FileHandler オブジェクト¶

FileHandler.file_open(req)¶: ホスト名がない場合、またはホスト名が 'localhost' の場合にファイルをローカルでオープンします。

バージョン 3.2 で変更: このメソッドはローカルのホスト名に対してのみ適用可能です。リモートホスト名が与えられた場合、URLError が送出されます。

DataHandler オブジェクト¶

DataHandler.data_open(req)¶: data URL を読み込みます。この種類の URL は、URL 自体にエンコードされた内容を含みます。 data URL の構文は RFC 2397 で規定されています。この実装は base64 エンコードされた data URL 内の空白文字を無視するため、URL を記述するソースファイル内で折り返しても構いません。ただし、一部のブラウザとは異なり、base64 エンコードされた data URL の末尾のパディングが欠けていると、この実装は ValueError を送出します。

FTPHandler オブジェクト¶

FTPHandler.ftp_open(req)¶: req で表されるファイルを FTP 越しにオープンします。ログインは常に空のユーザネームおよびパスワードで行われます。

CacheFTPHandler オブジェクト¶

CacheFTPHandler オブジェクトは FTPHandler オブジェクトに以下のメソッドを追加したものです:

CacheFTPHandler.setTimeout(t)¶: 接続のタイムアウトを t 秒に設定します。

CacheFTPHandler.setMaxConns(m)¶: キャッシュ付き接続の最大接続数を m に設定します。

UnknownHandler オブジェクト¶

UnknownHandler.unknown_open()¶: URLError 例外を送出します。

HTTPErrorProcessor オブジェクト¶

HTTPErrorProcessor.http_response(request, response)¶

HTTP エラー応答の処理をします。

エラーコード 200 の場合、レスポンスオブジェクトを即座に返します。

200 以外のエラーコードの場合、これは単に http_error_<type>() ハンドラーメソッドに OpenerDirector.error() 経由で処理を渡します。他にそのエラーを処理するハンドラーがない場合、HTTPDefaultErrorHandler は最後に HTTPError を送出します。

HTTPErrorProcessor.https_response(request, response)¶

HTTPS エラー応答の処理をします。

振る舞いは http_response() と同じです。

使用例¶

以下の例の他に urllib パッケージを使ってインターネット上のリソースを取得するにはに多くの例があります。

以下の例では、python.org のメインページを取得して、その最初の 300 バイト分を表示します。

>>> import urllib.request
>>> with urllib.request.urlopen('https://www.python.org/') as f:
...     # レスポンスは圧縮されている場合がある (例: 'gzip')。
...     print(f.headers.get('Content-Encoding'))
...     data = f.read()
...     if f.headers.get('Content-Encoding') == 'gzip':
...         import gzip
...         data = gzip.decompress(data)
...     print(data[:300].decode('utf-8', errors='replace'))

urlopen は bytes オブジェクトを返すことに注意してください。これは urlopen が、HTTP サーバーから受信したバイトストリームのエンコーディングを自動的に決定できないためです。一般に、返された bytes オブジェクトを文字列にデコードするためのエンコーディングの決定あるいは推測はプログラム側が行います。

以下の HTML の仕様ドキュメント https://html.spec.whatwg.org/#charset には HTML や XML ドキュメントでそのエンコーディング情報を指定するさまざまな方法の一覧があります。

追加の情報は、W3C の文書 https://www.w3.org/International/questions/qa-html-encoding-declarations を参照してください。

python.org ウェブサイトでは utf-8 エンコーディングを使用しており、それをその meta タグで指定していますので、bytes オブジェクトのデコードも同様に行います。

>>> with urllib.request.urlopen('https://www.python.org/') as f:
...     # 圧縮されているか確認し、適切にデコードする。
...     enc = f.headers.get('Content-Encoding')
...     data = f.read()
...     if enc == 'gzip':
...         import gzip
...         data = gzip.decompress(data)
...     print(data[:100].decode('utf-8', errors='replace'))
...

コンテキストマネージャーを使用しないアプローチでも同様の結果を得ることができます。

>>> import urllib.request
>>> f = urllib.request.urlopen('https://www.python.org/')
>>> try:
...     enc = f.headers.get('Content-Encoding')
...     data = f.read()
...     if enc == 'gzip':
...         import gzip
...         data = gzip.decompress(data)
...     print(data[:100].decode('utf-8', errors='replace'))
... finally:
...     f.close()

以下の例では、データストリームを 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
# Basic HTTP 認証に対応する OpenerDirector を作成する。
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)
# urlopen で使えるようにグローバルにインストールする。
urllib.request.install_opener(opener)
with urllib.request.urlopen('http://www.example.com/login.html') as f:
    print(f.read().decode('utf-8'))

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)
# 今回は OpenerDirector をインストールせず、直接使う。
with opener.open('http://www.example.com/login.html') as f:
   print(f.read().decode('utf-8'))

以下は HTTP ヘッダーを追加する例です:

headers 引数を使って Request コンストラクタを呼び出す方法の他に、以下のようにできます:

import urllib.request
req = urllib.request.Request('http://www.example.com/')
req.add_header('Referer', 'https://www.python.org/')
# デフォルトの User-Agent ヘッダーの値を変更する。
req.add_header('User-Agent', 'urllib-example/0.1 (Contact: . . .)')
with urllib.request.urlopen(req) as f:
    print(f.read().decode('utf-8'))

OpenerDirector は全ての Request に User-Agent ヘッダーを自動的に追加します。これを変更するには以下のようにします:

import urllib.request
opener = urllib.request.build_opener()
opener.addheaders = [('User-agent', 'Mozilla/5.0')]
with opener.open('http://www.example.com/') as f:
   print(f.read().decode('utf-8'))

また、 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 = "https://www.python.org/?%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("https://httpbin.org/post", data) as f:
...     print(f.read().decode('utf-8'))
...

以下の例では、環境変数による設定内容に対して上書きする形で HTTP プロキシを明示的に設定しています:

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

以下の例では、環境変数による設定内容に対して上書きする形で、まったくプロキシを使わないよう設定しています:

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

レガシーインターフェース¶

以下の関数とクラスは、Python 2 の urllib モジュール (urllib2 ではありません) から移植されたものです。将来のいずれかの時点で非推奨になる可能性があります。

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

URL で表されるネットワークオブジェクトをローカルファイルにコピーします。 URL がローカルファイルを示している場合は、ファイル名が与えられない限りオブジェクトはコピーされません。戻り値はタプル (filename, headers) になり、 filename はオブジェクトが保存されたローカルファイル名、 headers は (リモートオブジェクトに対しては) urlopen() が返したオブジェクトの info() メソッドが返すものすべてになります。例外は urlopen() のものと同じになります。

第 2 引数を指定すると、コピー先のファイルの場所になります (省略すると、生成された名前を持つ一時ファイルになります)。第 3 引数を指定する場合は、呼び出し可能オブジェクトにしてください。ネットワーク接続が確立したときに一度、その後はブロックを読み込むたびに一度呼び出されます。このオブジェクトには、それまでに転送したブロック数、バイト単位のブロックサイズ、ファイルの合計サイズの三つの引数が渡されます。取得リクエストに対してファイルサイズを返さない古い FTP サーバーでは、この第 3 引数が -1 になる場合があります。

以下は最も一般的な使用例です:

>>> import urllib.request
>>> local_filename, headers = urllib.request.urlretrieve('https://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() の呼び出しで残った一時ファイルを削除します。また、install_opener() で設定したデフォルトのグローバル opener もリセットします。

`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 モジュールを使用します。

`urllib.response` --- urllib が使うレスポンスクラス¶

urllib.response モジュールは、read() や readline() などの最小限のファイルライクなインターフェースを定義する関数とクラスを提供します。このモジュールが定義する関数は urllib.request モジュールの内部で使われます。典型的なレスポンスオブジェクトは urllib.response.addinfourl のインスタンスです:

class urllib.response.addinfourl¶

url¶: 取得されたリソースの URL、主にリダイレクトが発生したかどうかを確認するために利用します。

headers¶: Returns the headers of the response in the form of an EmailMessage instance.

status¶: Added in version 3.9.

サーバから返される状態コードです。

geturl()¶: バージョン 3.9 で非推奨: 非推奨となったので url を使用してください。

info()¶: バージョン 3.9 で非推奨: 非推奨となったので headers を使用してください。

code¶: バージョン 3.9 で非推奨: 非推奨となったので status を使用してください。

getcode()¶: バージョン 3.9 で非推奨: 非推奨となったので status を使用してください。

`urllib.request` --- URL を開くための拡張可能なライブラリ¶

Request オブジェクト¶

OpenerDirector オブジェクト¶

BaseHandler オブジェクト¶

HTTPRedirectHandler オブジェクト¶

HTTPCookieProcessor オブジェクト¶

ProxyHandler オブジェクト¶

HTTPPasswordMgr オブジェクト¶

HTTPPasswordMgrWithPriorAuth オブジェクト¶

AbstractBasicAuthHandler オブジェクト¶

HTTPBasicAuthHandler オブジェクト¶

ProxyBasicAuthHandler オブジェクト¶

AbstractDigestAuthHandler オブジェクト¶

HTTPDigestAuthHandler オブジェクト¶

ProxyDigestAuthHandler オブジェクト¶

HTTPHandler オブジェクト¶

HTTPSHandler オブジェクト¶

FileHandler オブジェクト¶

DataHandler オブジェクト¶

FTPHandler オブジェクト¶

CacheFTPHandler オブジェクト¶

UnknownHandler オブジェクト¶

HTTPErrorProcessor オブジェクト¶

使用例¶

レガシーインターフェース¶

`urllib.request` の制約¶

`urllib.response` --- urllib が使うレスポンスクラス¶

目次

前のトピックへ

次のトピックへ

このページ

urllib.request --- URL を開くための拡張可能なライブラリ¶

Request オブジェクト¶

OpenerDirector オブジェクト¶

BaseHandler オブジェクト¶

HTTPRedirectHandler オブジェクト¶

HTTPCookieProcessor オブジェクト¶

ProxyHandler オブジェクト¶

HTTPPasswordMgr オブジェクト¶

HTTPPasswordMgrWithPriorAuth オブジェクト¶

AbstractBasicAuthHandler オブジェクト¶

HTTPBasicAuthHandler オブジェクト¶

ProxyBasicAuthHandler オブジェクト¶

AbstractDigestAuthHandler オブジェクト¶

HTTPDigestAuthHandler オブジェクト¶

ProxyDigestAuthHandler オブジェクト¶

HTTPHandler オブジェクト¶

HTTPSHandler オブジェクト¶

FileHandler オブジェクト¶

DataHandler オブジェクト¶

FTPHandler オブジェクト¶

CacheFTPHandler オブジェクト¶

UnknownHandler オブジェクト¶

HTTPErrorProcessor オブジェクト¶

使用例¶

レガシーインターフェース¶

urllib.request の制約¶

urllib.response --- urllib が使うレスポンスクラス¶

`urllib.request` --- URL を開くための拡張可能なライブラリ¶

`urllib.request` の制約¶

`urllib.response` --- urllib が使うレスポンスクラス¶