# `urllib.request` --- URL を開くための大規模なライブラリ

ソースコード: Lib/urllib/request.py

`urllib.request` モジュールは基本的な認証、暗号化認証、リダイレクション、Cookie、その他の介在する複雑なアクセス環境において (大抵は HTTP で) URL を開くための関数とクラスを定義します。

参考

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

警告

On macOS it is unsafe to use this module in programs using `os.fork()` because the `getproxies()` implementation for macOS uses a higher-level system API. Set the environment variable `no_proxy` to `*` to avoid this problem (e.g. `os.environ["no_proxy"] = "*"`).

Availability: not WASI.

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

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

urllib.request.urlopen(url, data=None, [timeout, ]*, context=None)

  Open url, which can be either a string containing a valid, properly encoded URL, or a `Request` object.

  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 フレーズ --- と同じ情報を含んでいます。

  For FTP, file, and data URLs and requests explicitly handled by legacy `URLopener` and `FancyURLopener` classes, this function returns a `urllib.response.addinfourl` object.

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

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

  In addition, if proxy settings are detected (for example, when a `*_proxy` environment variable like `http_proxy` is set), `ProxyHandler` is default installed and makes sure the requests are handled through the proxy.

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

  The default opener raises an auditing event `urllib.Request` with arguments `fullurl`, `data`, `headers`, `method` taken from the request object.

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

  HTTPS virtual hosts are now supported if possible (that is, if `ssl.HAS_SNI` is true).

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

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

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

  バージョン 3.10 で変更: HTTPS connection now send an ALPN extension with protocol indicator `http/1.1` when no context is given. Custom context should set ALPN protocols with `set_alpn_protocols()`.

  バージョン 3.13 で変更: Remove cafile, capath and cadefault parameters: use the context parameter instead.

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)

  Convert the given local path to a `file:` URL. This function uses `quote()` function to encode the path. For historical reasons, the return value omits the `file:` scheme prefix. This example shows the function being used on Windows:

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

urllib.request.url2pathname(url)

  Convert the given `file:` URL to a local path. This function uses `unquote()` to decode the URL. For historical reasons, the given value must omit the `file:` scheme prefix. This example shows the function being used on Windows:

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

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 should be a string containing a valid, properly encoded 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 of bytes-like objects. If no `Content-Length` nor `Transfer-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, while `Transfer-Encoding: chunked` as specified in RFC 7230, Section 3.3.1 will be used to send files and other iterables.

  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のすべてのキーはキャメルケースで送信されます。

  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.

  次の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 should be a string that indicates the HTTP request method that will be used (e.g. `'HEAD'`). If provided, its value is stored in the `method` attribute and is used by `get_method()`. The default is `'GET'` if data is `None` or `'POST'` otherwise. Subclasses may indicate a different default method by setting the `method` 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 neither `None` 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 環境では、 レジストリのインターネット設定セクションからプロキシ設定を手に入れ、 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 オブジェクト を参照してください。

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 should be an instance of `BaseHandler`. The following methods are searched, and added to the possible chains (note that HTTP errors are a special case). Note that, in the following, protocol should be replaced with the actual protocol to handle, for example `http_response()` would be the HTTP protocol response handler. Also type should be replaced with the actual HTTP code, for example `http_error_404()` would handle HTTP 404 errors.

  - `<protocol>_open()` --- signal that the handler knows how to open protocol URLs.

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

  - `http_error_<type>()` --- signal that the handler knows how to handle HTTP errors with HTTP error code type.

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

  - `<protocol>_error()` --- signal that the handler knows how to handle errors from (non-`http`) protocol.

  - `<protocol>_request()` --- signal that the handler knows how to pre-process protocol requests.

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

  - `<protocol>_response()` --- signal that the handler knows how to post-process protocol responses.

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

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

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

OpenerDirector.error(proto, *args)

  Handle an error of the given protocol. This will call the registered error handlers for the given protocol with the given arguments (which are protocol specific). The HTTP protocol is a special case which uses the HTTP response code to determine the specific error handler; refer to the `http_error_<type>()` methods of the handler classes.

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

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

各ステージで OpenerDirector オブジェクトのメソッドがどのような順で呼び出されるかは、ハンドラインスタンスの並び方で決まります。

1. Every handler with a method named like `<protocol>_request()` has that method called to pre-process the request.

2. Handlers with a method named like `<protocol>_open()` are called to handle the request. This stage ends when a handler either returns a non-`None` value (ie. a response), or raises an exception (usually `URLError`). Exceptions are allowed to propagate.

   In fact, the above algorithm is first tried for methods named `default_open()`. If all such methods return `None`, the algorithm is repeated for methods named like `<protocol>_open()`. If all such methods return `None`, the algorithm is repeated for methods named `unknown_open()`.

   これらのメソッドの実装には、親となる `OpenerDirector` インスタンスの `open()` や `error()` といったメソッド呼び出しが入る場合があるので注意してください。

3. Every handler with a method named like `<protocol>_response()` has that method called to post-process the response.

## BaseHandler オブジェクト

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

BaseHandler.add_parent(director)

  親オブジェクトとして、 `director` を追加します。

BaseHandler.close()

  全ての親オブジェクトを削除します。

以下の属性およびメソッドは `BaseHandler` から派生したクラスでのみ使われます。

注釈

The convention has been adopted that subclasses defining `<protocol>_request()` or `<protocol>_response()` methods are named `*Processor`; all others are named `*Handler`.

BaseHandler.parent

  有効な `OpenerDirector` です。この値は違うプロトコルを使って URL を開く場合やエラーを処理する際に使われます。

BaseHandler.default_open(req)

  このメソッドは `BaseHandler` では定義されて いません 。しかし、全ての URL をキャッチさせたいなら、サブクラスで定義する 必要があります。

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

  このメソッドはプロトコル固有のオープンメソッドが呼び出される前に呼び出されます。

BaseHandler.<protocol>_open(req)

  このメソッドは `BaseHandler` では定義されて いません 。しかしプロトコルの URL をキャッチしたいなら、サブクラスで定義する必要があります。

  This method, if defined, will be called by the parent `OpenerDirector`. Return values should be the same as for `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` will call this method with five positional arguments:

  1. a `Request` object,

  2. a file-like object with the HTTP error body,

  3. the three-digit code of the error, as a string,

  4. the user-visible explanation of the code, as a string, and

  5. the headers of the error, as a mapping object.

  返される値および送出される例外は `urlopen()` と同じものでなければなりません。

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

  nnn は 3 桁の 10 進数からなる HTTP エラーコードでなくてはなりません。このメソッドも `BaseHandler` では定義されていませんが、サブクラスのインスタンスで定義されていた場合、エラーコード nnn の HTTP エラーが発生した際に呼び出されます。

  特定の HTTP エラーに対する処理を行うためには、このメソッドをサブクラスでオーバライドする必要があります。

  Arguments, return values and exceptions raised should be the same as for `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 を参照してください。

An `HTTPError` exception raised as a security consideration if the HTTPRedirectHandler is presented with a redirected URL which is not an HTTP, HTTPS or FTP URL.

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

  Return a `Request` or `None` in response to a redirect. This is called by the default implementations of the `http_error_30*()` methods when a redirection is received from the server. If a redirection should take place, return a new `Request` to allow `http_error_30*()` to perform the redirect to newurl. Otherwise, raise `HTTPError` if no other handler should try to handle this URL, or return `None` if you can't but another handler might.

  注釈

  このメソッドのデフォルトの実装は、 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)

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

  Added in version 3.11.

## HTTPCookieProcessor オブジェクト

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

HTTPCookieProcessor.cookiejar

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

## ProxyHandler オブジェクト

ProxyHandler.<protocol>_open(request)

  The `ProxyHandler` will have a method `<protocol>_open()` for every protocol which has a proxy in the proxies dictionary given in the constructor. The method will modify requests to go through the proxy, by calling `request.set_proxy()`, and call the next handler in the chain to actually execute the protocol.

## 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` が検索されます。

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

  与えられた url や 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 はエラーヘッダーでなくてはなりません。

  host は、オーソリティ (例 `"python.org"`) か、オーソリティコンポーネントを含む URL (例 `"http://python.org"`) です。どちらの場合も、オーソリティはユーザ情報コンポーネントを含んではいけません (なので、 `"python.org"` や `"python.org:80"` は正しく、 `"joe:password@python.org"` は不正です) 。

## HTTPBasicAuthHandler オブジェクト

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

  認証情報がある場合、認証情報付きで再度リクエストを試みます。

## ProxyBasicAuthHandler オブジェクト

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

  認証情報がある場合、認証情報付きで再度リクエストを試みます。

## AbstractDigestAuthHandler オブジェクト

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

  authreq はリクエストにおいてレルムに関する情報が含まれているヘッダーの名前、 host は認証を行う対象のホスト名、 req は (失敗した) `Request` オブジェクト、そして headers はエラーヘッダーでなくてはなりません。

## HTTPDigestAuthHandler オブジェクト

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

  認証情報がある場合、認証情報付きで再度リクエストを試みます。

## ProxyDigestAuthHandler オブジェクト

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

  認証情報がある場合、認証情報付きで再度リクエストを試みます。

## HTTPHandler オブジェクト

HTTPHandler.http_open(req)

  Send an HTTP request, which can be either GET or POST, depending on `req.data`.

## HTTPSHandler オブジェクト

HTTPSHandler.https_open(req)

  Send an HTTPS request, which can be either GET or POST, depending on `req.data`.

## FileHandler オブジェクト

FileHandler.file_open(req)

  ホスト名がない場合、またはホスト名が `'localhost'` の場合にファイルをローカルでオープンします。

  バージョン 3.2 で変更: This method is applicable only for local hostnames. When a remote hostname is given, a `URLError` is raised.

## 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 a `ValueError` in that case.

## 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 の場合、レスポンスオブジェクトを即座に返します。

  For non-200 error codes, this simply passes the job on to the `http_error_<type>()` handler methods, via `OpenerDirector.error()`. Eventually, `HTTPDefaultErrorHandler` will raise an `HTTPError` if no other handler handles the error.

HTTPErrorProcessor.https_response(request, response)

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

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

## 使用例

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

This example gets the python.org main page and displays the first 300 bytes of it:

    >>> import urllib.request
    >>> with urllib.request.urlopen('http://www.python.org/') as f:
    ...     print(f.read(300))
    ...
    b'<!doctype html>\n<!--[if lt IE 7]>   <html class="no-js ie6 lt-ie7 lt-ie8 lt-ie9">   <![endif]-->\n<!--[if IE 7]>      <html class="no-js ie7 lt-ie8 lt-ie9">          <![endif]-->\n<!--[if IE 8]>      <html class="no-js ie8 lt-ie9">

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

The following HTML spec document, https://html.spec.whatwg.org/#charset, lists the various ways in which an HTML or an XML document could have specified its encoding information.

For additional information, see the W3C document: https://www.w3.org/International/questions/qa-html-encoding-declarations.

As the python.org website uses utf-8 encoding as specified in its meta tag, we will use the same for decoding the bytes object:

    >>> with urllib.request.urlopen('http://www.python.org/') as f:
    ...     print(f.read(100).decode('utf-8'))
    ...
    <!doctype html>
    <!--[if lt IE 7]>   <html class="no-js ie6 lt-ie7 lt-ie8 lt-ie9">   <![endif]-->
    <!-

It is also possible to achieve the same result without using the context manager approach:

    >>> import urllib.request
    >>> f = urllib.request.urlopen('http://www.python.org/')
    >>> try:
    ...     print(f.read(100).decode('utf-8'))
    ... finally:
    ...     f.close()
    ...
    <!doctype html>
    <!--[if lt IE 7]>   <html class="no-js ie6 lt-ie7 lt-ie8 lt-ie9">   <![endif]-->
    <!--

以下の例では、データストリームを 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)
    with urllib.request.urlopen('http://www.example.com/login.html') as f:
        print(f.read().decode('utf-8'))

`build_opener()` provides many handlers by default, including a `ProxyHandler`. By default, `ProxyHandler` uses the environment variables named `<scheme>_proxy`, where `<scheme>` is the URL scheme involved. For example, the `http_proxy` environment variable is read to obtain the HTTP proxy's URL.

この例では、デフォルトの `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:
    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', 'http://www.python.org/')
    # Customize the default User-Agent header value:
    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 = "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')
    ...

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

以下の関数およびクラスは、Python 2 のモジュール `urllib` (`urllib2` ではありません) から移植されたものです。これらは将来的に廃止されるかもしれません。

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

  Copy a network object denoted by a URL to a local file. If the URL points to a local file, the object will not be copied unless filename is supplied. Return a tuple `(filename, headers)` where filename is the local file name under which the object can be found, and headers is whatever the `info()` method of the object returned by `urlopen()` returned (for a remote object). Exceptions are the same as for `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()` will raise `ContentTooShortError` when it detects that the amount of data available was less than the expected amount (which is the size reported by a Content-Length header). This can occur, for example, when the download is interrupted.

  Content-Length はデータ量の下限です: 読み込むデータ量がこれを超えている場合 urlretrieve はそれらも読み込みますが、利用できるデータがこれを下回った場合、例外が送出されます。

  You can still retrieve the downloaded data in this case, it is stored in the `content` attribute of the exception instance.

  Content-Length ヘッダーが与えられなれけば urlretrieve はダウンロードしたデータのサイズをチェックできません。この場合ダウンロードは正常に完了したとみなすしかありません。

urllib.request.urlcleanup()

  以前の `urlretrieve()` 呼び出し後に残っているかもしれない一時ファイルをクリーンアップします。

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

  バージョン 3.3 で非推奨.

  Base class for opening and reading URLs. Unless you need to support opening objects using schemes other than `http:`, `ftp:`, or `file:`, you probably want to use `FancyURLopener`.

  By default, the `URLopener` class sends a User-Agent header of `urllib/VVV`, where VVV is the `urllib` version number. Applications can define their own User-Agent header by subclassing `URLopener` or `FancyURLopener` and setting the class attribute `version` to an appropriate string value in the subclass definition.

  The optional proxies parameter should be a dictionary mapping scheme names to proxy URLs, where an empty dictionary turns proxies off completely. Its default value is `None`, in which case environmental proxy settings will be used if present, as discussed in the definition of `urlopen()`, above.

  Additional keyword parameters, collected in x509, may be used for authentication of the client when using the `https:` scheme. The keywords key_file and cert_file are supported to provide an SSL key and certificate; both are needed to support client authentication.

  `URLopener` objects will raise an `OSError` exception if the server returns an error code.

  open(fullurl, data=None)

    Open fullurl using the appropriate protocol. This method sets up cache and proxy information, then calls the appropriate open method with its input arguments. If the scheme is not recognized, `open_unknown()` is called. The data argument has the same meaning as the data argument of `urlopen()`.

    This method always quotes fullurl using `quote()`.

  open_unknown(fullurl, data=None)

    Overridable interface to open unknown URL types.

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

    Retrieves the contents of url and places it in filename. The return value is a tuple consisting of a local filename and either an `email.message.Message` object containing the response headers (for remote URLs) or `None` (for local URLs). The caller must then open and read the contents of filename. If filename is not given and the URL refers to a local file, the input filename is returned. If the URL is non-local and filename is not given, the filename is the output of `tempfile.mktemp()` with a suffix that matches the suffix of the last path component of the input URL. If reporthook is given, it must be a function accepting three numeric parameters: A chunk number, the maximum size chunks are read in and the total size of the download (-1 if unknown). It will be called once at the start and after each chunk of data is read from the network. reporthook is ignored for local URLs.

    If the url uses the `http:` scheme identifier, the optional data argument may be given to specify a `POST` request (normally the request type is `GET`). The data argument must in standard application/x-www-form-urlencoded format; see the `urllib.parse.urlencode()` function.

  version

    Variable that specifies the user agent of the opener object. To get `urllib` to tell servers that it is a particular user agent, set this in a subclass as a class variable or in the constructor before calling the base constructor.

class urllib.request.FancyURLopener(...)

  バージョン 3.3 で非推奨.

  `FancyURLopener` subclasses `URLopener` providing default handling for the following HTTP response codes: 301, 302, 303, 307 and 401. For the 30x response codes listed above, the Location header is used to fetch the actual URL. For 401 response codes (authentication required), basic HTTP authentication is performed. For the 30x response codes, recursion is bounded by the value of the maxtries attribute, which defaults to 10.

  For all other response codes, the method `http_error_default()` is called which you can override in subclasses to handle the error appropriately.

  注釈

  According to the letter of RFC 2616, 301 and 302 responses to POST requests must not be automatically redirected without confirmation by the user. In reality, browsers do allow automatic redirection of these responses, changing the POST to a GET, and `urllib` reproduces this behaviour.

  The parameters to the constructor are the same as those for `URLopener`.

  注釈

  When performing basic authentication, a `FancyURLopener` instance calls its `prompt_user_passwd()` method. The default implementation asks the users for the required information on the controlling terminal. A subclass may override this method to support more appropriate behavior if needed.

  The `FancyURLopener` class offers one additional method that should be overloaded to provide the appropriate behavior:

  prompt_user_passwd(host, realm)

    Return information needed to authenticate the user at the given host in the specified security realm. The return value should be a tuple, `(user, password)`, which can be used for basic authentication.

    The implementation prompts for this information on the terminal; an application should override this method to use an appropriate interaction model in the local environment.

## `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` を使用してこれを解析できます。

- The code handling the FTP protocol cannot differentiate between a file and a directory. This can lead to unexpected behavior when attempting to read a URL that points to a file that is not accessible. If the URL ends in a `/`, it is assumed to refer to a directory and will be handled accordingly. But if an attempt to read a file leads to a 550 error (meaning the URL cannot be found or is not accessible, often for permission reasons), then the path is treated as a directory in order to handle the case when a directory is specified by a URL but the trailing `/` has been left off. This can cause misleading results when you try to fetch a file whose read permissions make it inaccessible; the FTP code will try to read it, fail with a 550 error, and then perform a directory listing for the unreadable file. If fine-grained control is needed, consider using the `ftplib` module, subclassing `FancyURLopener`, or changing _urlopener to meet your needs.

# `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` を使用してください。