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

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

======================================================================

"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" を送出します。

   Exceptions raised while reading or parsing an HTTP response are not
   wrapped in "URLError" and propagate unchanged. These include
   subclasses of "http.client.HTTPException", such as "BadStatusLine"
   for a malformed status line, and subclasses of "OSError", such as
   "TimeoutError" if the server does not respond within *timeout*
   seconds, or "RemoteDisconnected" if the server closes the
   connection without sending a response.  "ValueError" is raised if
   *url* is not a valid URL.

   どのハンドラもリクエストを処理しなかった場合には "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 を開
きます:

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

1. "<protocol>_request()" 形式のメソッドを持つすべてのハンドラーに対し
   てそのメソッドを呼び出し、リクエストのプリプロセスを行います。

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

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

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

3. "<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" は五つの位置引数を渡してこのメソッドを呼び出します
   :

   1. "Request" オブジェクト

   2. HTTP エラーの本文を含むファイルライクオブジェクト

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

   4. 利用者向けのコードの説明を表す文字列

   5. エラーのヘッダーを表すマッピングオブジェクト

   返される値および送出される例外は "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" を使用して
      ください。
