"urllib.parse" --- URL を解析して構成要素にする
***********************************************

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

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

このモジュールでは URL (Uniform Resource Locator) 文字列をその構成要素
(アドレススキーム、ネットワーク上の位置、パスその他) に分解したり、構
成要素を URL に組みなおしたり、 "相対 URL (relative URL)" を指定した "
基底 URL (base URL)" に基づいて絶対 URL に変換するための標準的なインタ
ーフェースを定義しています。

このモジュールは Relative Uniform Resource Locators (相対 URL) に関す
るインターネット RFC に適合するよう設計されており、次の URL スキームを
サポートしています: "file", "ftp", "gopher", "hdl", "http", "https",
"imap", "mailto", "mms", "news", "nntp", "prospero", "rsync", "rtsp",
"rtspu", "sftp", "shttp", "sip", "sips", "snews", "svn", "svn+ssh",
"telnet", "wais", "ws", "wss"

"urllib.parse" モジュールは、大きく分けると URL の解析を行う関数と URL
のクオートを行う関数を定義しています。以下にこれらの詳細を説明します。


URL の解析
==========

URL 解析関数は、URL 文字列を各構成要素に分割するか、あるいは URL の構
成要素を組み合わせて URL 文字列を生成します。

urllib.parse.urlparse(urlstring, scheme='', allow_fragments=True)

   URL を解析して 6 つの構成要素にし、6 要素の *named tuple* を返しま
   す。このタプルは URL の一般的な構造:
   "scheme://netloc/path;parameters?query#fragment" に対応しています。
   各タプル要素は文字列で、空の場合もあります。構成要素がさらに小さい
   要素に分解されることはありません (例えばネットワーク上の位置は単一
   の文字列になります)。また % によるエスケープは展開されません。上で
   示された区切り文字がタプルの各要素の一部分として含まれることはあり
   ませんが、*path* 要素の先頭のスラッシュがある場合には例外です。たと
   えば以下のようになります:

      >>> from urllib.parse import urlparse
      >>> urlparse("scheme://netloc/path;parameters?query#fragment")
      ParseResult(scheme='scheme', netloc='netloc', path='/path;parameters', params='',
                  query='query', fragment='fragment')
      >>> o = urlparse("http://docs.python.org:80/3/library/urllib.parse.html?"
      ...              "highlight=params#url-parsing")
      >>> o
      ParseResult(scheme='http', netloc='docs.python.org:80',
                  path='/3/library/urllib.parse.html', params='',
                  query='highlight=params', fragment='url-parsing')
      >>> o.scheme
      'http'
      >>> o.netloc
      'docs.python.org:80'
      >>> o.hostname
      'docs.python.org'
      >>> o.port
      80
      >>> o._replace(fragment="").geturl()
      'http://docs.python.org:80/3/library/urllib.parse.html?highlight=params'

   **RFC 1808** にある文法仕様に基づき、urlparse は '//' で始まる場合
   にのみ netloc を認識します。それ以外の場合は、入力は相対URLであると
   推定され、path 部分で始まることになります。

      >>> from urllib.parse import urlparse
      >>> urlparse('//www.cwi.nl:80/%7Eguido/Python.html')
      ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
                  params='', query='', fragment='')
      >>> urlparse('www.cwi.nl/%7Eguido/Python.html')
      ParseResult(scheme='', netloc='', path='www.cwi.nl/%7Eguido/Python.html',
                  params='', query='', fragment='')
      >>> urlparse('help/Python.html')
      ParseResult(scheme='', netloc='', path='help/Python.html', params='',
                  query='', fragment='')

   *scheme* 引数によってデフォルトのアドレススキームを与えると、アドレ
   ススキームを指定していない URL のみに使用されます。常に許されるデフ
   ォルトの "''" ("b''" に自動変換出来る)を除き、 *urlstring* と同じ型
   (テキストもしくはバイト列)であるべきです。

   引数 *allow_fragments* が false の場合、フラグメント識別子は認識さ
   れません。その代わり、それはパス、パラメータ、またはクエリ要素の一
   部として解析され、戻り値の "fragment" は空文字に設定されます。

   戻り値は *名前付きタプル* です。これは、インデックス指定もしくは以
   下のような名前属性で要素にアクセスできることを意味します:

   +--------------------+---------+---------------------------+--------------------------+
   | 属性               | インデ  | 値                        | 指定されなかった場合の値 |
   |                    | ックス  |                           |                          |
   |====================|=========|===========================|==========================|
   | "scheme"           | 0       | URL スキーム              | *scheme* パラメータ      |
   +--------------------+---------+---------------------------+--------------------------+
   | "netloc"           | 1       | ネットワーク上の位置      | 空文字列                 |
   +--------------------+---------+---------------------------+--------------------------+
   | "path"             | 2       | 階層的パス                | 空文字列                 |
   +--------------------+---------+---------------------------+--------------------------+
   | "params"           | 3       | 最後のパス要素に対するパ  | 空文字列                 |
   |                    |         | ラメータ                  |                          |
   +--------------------+---------+---------------------------+--------------------------+
   | "query"            | 4       | クエリ要素                | 空文字列                 |
   +--------------------+---------+---------------------------+--------------------------+
   | "fragment"         | 5       | フラグメント識別子        | 空文字列                 |
   +--------------------+---------+---------------------------+--------------------------+
   | "username"         |         | ユーザ名                  | "None"                   |
   +--------------------+---------+---------------------------+--------------------------+
   | "password"         |         | パスワード                | "None"                   |
   +--------------------+---------+---------------------------+--------------------------+
   | "hostname"         |         | ホスト名 (小文字)         | "None"                   |
   +--------------------+---------+---------------------------+--------------------------+
   | "port"             |         | ポート番号を表わす整数 (  | "None"                   |
   |                    |         | もしあれば)               |                          |
   +--------------------+---------+---------------------------+--------------------------+

   URL中で不正なポートが指定されている場合、 "port" 属性を読みだすと、
   "ValueError" を送出します。結果オブジェクトのより詳しい情報は 構造
   化された解析結果 節を参照してください。

   "netloc" 属性にマッチしなかった角括弧があると "ValueError" を送出し
   ます。

   Characters in the "netloc" attribute that decompose under NFKC
   normalization (as used by the IDNA encoding) into any of "/", "?",
   "#", "@", or ":" will raise a "ValueError". If the URL is
   decomposed before parsing, no error will be raised.

   As is the case with all named tuples, the subclass has a few
   additional methods and attributes that are particularly useful. One
   such method is "_replace()". The "_replace()" method will return a
   new ParseResult object replacing specified fields with new values.

      >>> from urllib.parse import urlparse
      >>> u = urlparse('//www.cwi.nl:80/%7Eguido/Python.html')
      >>> u
      ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
                  params='', query='', fragment='')
      >>> u._replace(scheme='http')
      ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
                  params='', query='', fragment='')

   警告:

     "urlparse()" does not perform validation.  See URL parsing
     security for details.

   バージョン 3.2 で変更: IPv6 URL の解析も行えるようになりました。

   バージョン 3.3 で変更: **RFC 3986** に従い、fragment はすべての URL
   スキームに対して解析されるようになりました (*allow_fragment* が偽の
   場合は除く)。

   バージョン 3.6 で変更: 範囲外のポート番号を指定すると、 "None" を返
   す代わりに、"ValueError" を送出するようになりました。

   バージョン 3.8 で変更: Characters that affect netloc parsing under
   NFKC normalization will now raise "ValueError".

urllib.parse.parse_qs(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')

   文字列引数として渡されたクエリ文字列  (*application/x-www-form-
   urlencoded* 型のデータ) を解析します。解析されたデータを辞書として
   返します。辞書のキーは一意なクエリ変数名で、値は各変数名に対する値
   からなるリストです。

   任意の引数 *keep_blank_values* は、パーセントエンコードされたクエリ
   の中の値が入っていないクエリの値を空白文字列と見なすかどうかを示す
   フラグです。値が真であれば、値の入っていないフィールドは空文字列の
   ままになります。標準では偽で、値の入っていないフィールドを無視し、
   そのフィールドはクエリに含まれていないものとして扱います。

   任意の引数 *strict_parsing* はパース時のエラーをどう扱うかを決める
   フラグです。値が偽なら (デフォルトの設定です)、エラーは暗黙のうちに
   無視します。値が真なら "ValueError" 例外を送出します。

   任意のパラメータ *encoding* および *errors* はパーセントエンコード
   されたシーケンスを Unicode 文字にデコードする方法を指定します。これ
   は "bytes.decode()" メソッドに渡されます。

   The optional argument *max_num_fields* is the maximum number of
   fields to read. If set, then throws a "ValueError" if there are
   more than *max_num_fields* fields read.

   The optional argument *separator* is the symbol to use for
   separating the query arguments. It defaults to "&".

   このような辞書をクエリ文字列に変換するには
   "urllib.parse.urlencode()" 関数を ("doseq" パラメータに "True" を指
   定して) 使用します。

   バージョン 3.2 で変更: *encoding* および *errors* パラメータが追加
   されました。

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

   バージョン 3.9.2 で変更: Added *separator* parameter with the
   default value of "&". Python versions earlier than Python 3.9.2
   allowed using both ";" and "&" as query parameter separator. This
   has been changed to allow only a single separator key, with "&" as
   the default separator.

urllib.parse.parse_qsl(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')

   文字列引数として渡されたクエリ文字列 (*application/x-www-form-
   urlencoded* 型のデータ) を解析します。解析されたデータは名前と値の
   ペアからなるリストです。

   任意の引数 *keep_blank_values* は、パーセントエンコードされたクエリ
   の中の値が入っていないクエリの値を空白文字列と見なすかどうかを示す
   フラグです。値が真であれば、値の入っていないフィールドは空文字列の
   ままになります。標準では偽で、値の入っていないフィールドを無視し、
   そのフィールドはクエリに含まれていないものとして扱います。

   任意の引数 *strict_parsing* はパース時のエラーをどう扱うかを決める
   フラグです。値が偽なら (デフォルトの設定です)、エラーは暗黙のうちに
   無視します。値が真なら "ValueError" 例外を送出します。

   任意のパラメータ *encoding* および *errors* はパーセントエンコード
   されたシーケンスを Unicode 文字にデコードする方法を指定します。これ
   は "bytes.decode()" メソッドに渡されます。

   The optional argument *max_num_fields* is the maximum number of
   fields to read. If set, then throws a "ValueError" if there are
   more than *max_num_fields* fields read.

   The optional argument *separator* is the symbol to use for
   separating the query arguments. It defaults to "&".

   ペアのリストからクエリ文字列を生成する場合には
   "urllib.parse.urlencode()" 関数を使用します。

   バージョン 3.2 で変更: *encoding* および *errors* パラメータが追加
   されました。

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

   バージョン 3.9.2 で変更: Added *separator* parameter with the
   default value of "&". Python versions earlier than Python 3.9.2
   allowed using both ";" and "&" as query parameter separator. This
   has been changed to allow only a single separator key, with "&" as
   the default separator.

urllib.parse.urlunparse(parts)

   "urlparse()" が返すような形式のタプルから URL を構築します。*parts*
   引数は任意の 6 要素イテラブルです。解析された元の URL が、不要な区
   切り文字を持っていた場合には、多少違いはあるが等価な URL になるかも
   しれません (例えばクエリ内容が空の "?" のようなもので、RFC はこれら
   を等価だと述べています)。

urllib.parse.urlsplit(urlstring, scheme='', allow_fragments=True)

   "urlparse()" に似ていますが、URL から params を切り離しません。この
   メソッドは通常、URL の *path* 部分において、各セグメントにパラメー
   タ指定をできるようにした最近の URL 構文 (**RFC 2396** 参照) が必要
   な場合に、 "urlparse()" の代わりに使われます。パスセグメントとパラ
   メータを分割するためには分割用の関数が必要です。この関数は 5 要素の
   *named tuple* を返します:

      (addressing scheme, network location, path, query, fragment identifier).

   戻り値は *名前付きタプル* で、インデックスによってもしくは名前属性
   として要素にアクセスできます:

   +--------------------+---------+---------------------------+------------------------+
   | 属性               | インデ  | 値                        | 指定されなかった場合の |
   |                    | ックス  |                           | 値                     |
   |====================|=========|===========================|========================|
   | "scheme"           | 0       | URL スキーム              | *scheme* パラメータ    |
   +--------------------+---------+---------------------------+------------------------+
   | "netloc"           | 1       | ネットワーク上の位置      | 空文字列               |
   +--------------------+---------+---------------------------+------------------------+
   | "path"             | 2       | 階層的パス                | 空文字列               |
   +--------------------+---------+---------------------------+------------------------+
   | "query"            | 3       | クエリ要素                | 空文字列               |
   +--------------------+---------+---------------------------+------------------------+
   | "fragment"         | 4       | フラグメント識別子        | 空文字列               |
   +--------------------+---------+---------------------------+------------------------+
   | "username"         |         | ユーザ名                  | "None"                 |
   +--------------------+---------+---------------------------+------------------------+
   | "password"         |         | パスワード                | "None"                 |
   +--------------------+---------+---------------------------+------------------------+
   | "hostname"         |         | ホスト名 (小文字)         | "None"                 |
   +--------------------+---------+---------------------------+------------------------+
   | "port"             |         | ポート番号を表わす整数 (  | "None"                 |
   |                    |         | もしあれば)               |                        |
   +--------------------+---------+---------------------------+------------------------+

   URL中で不正なポートが指定されている場合、 "port" 属性を読みだすと、
   "ValueError" を送出します。結果オブジェクトのより詳しい情報は 構造
   化された解析結果 節を参照してください。

   "netloc" 属性にマッチしなかった角括弧があると "ValueError" を送出し
   ます。

   Characters in the "netloc" attribute that decompose under NFKC
   normalization (as used by the IDNA encoding) into any of "/", "?",
   "#", "@", or ":" will raise a "ValueError". If the URL is
   decomposed before parsing, no error will be raised.

   Following some of the WHATWG spec that updates RFC 3986, leading C0
   control and space characters are stripped from the URL. "\n", "\r"
   and tab "\t" characters are removed from the URL at any position.

   警告:

     "urlsplit()" does not perform validation.  See URL parsing
     security for details.

   バージョン 3.6 で変更: 範囲外のポート番号を指定すると、 "None" を返
   す代わりに、"ValueError" を送出するようになりました。

   バージョン 3.8 で変更: Characters that affect netloc parsing under
   NFKC normalization will now raise "ValueError".

   バージョン 3.9.5 で変更: ASCII newline and tab characters are
   stripped from the URL.

   バージョン 3.9.17 で変更: Leading WHATWG C0 control and space
   characters are stripped from the URL.

urllib.parse.urlunsplit(parts)

   "urlsplit()" が返すような形式のタプル中のエレメントを組み合わせて、
   文字列の完全な URL にします。 *parts* 引数は任意の 5 要素イテラブル
   です。解析された元の URL が、不要な区切り文字を持っていた場合には、
   多少違いはあるが等価な URL になるかもしれません (例えばクエリ内容が
   空の ? のようなもので、RFC はこれらを等価だと述べています)。

urllib.parse.urljoin(base, url, allow_fragments=True)

   "基底 URL"(*base*)と別のURL(*url*)を組み合わせて、完全な URL ("絶対
   URL") を構成します。くだけて言えば、この関数は相対 URL にない要素を
   提供するために基底 URL の要素、特にアドレススキーム、ネットワーク上
   の位置、およびパス (の一部) を使います。例えば:

   >>> from urllib.parse import urljoin
   >>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')
   'http://www.cwi.nl/%7Eguido/FAQ.html'

   *allow_fragments* 引数は "urlparse()" における引数と同じ意味とデフ
   ォルトを持ちます。

   注釈:

     *url* が ("//" か "scheme://" で始まる) 絶対URLであれば、その
     *url* のホスト名と / もしくは scheme は結果に反映されます。例えば
     :

        >>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',
        ...         '//www.python.org/%7Eguido')
        'http://www.python.org/%7Eguido'

     もしこの動作が望みのものでない場合は、 *url* を "urlsplit()" と
     "urlunsplit()" で先に処理して、 *scheme* と *netloc* を削除してく
     ださい。

   バージョン 3.5 で変更: **RFC 3986** で定義された意味論とマッチする
   ように挙動がアップデートされました。

urllib.parse.urldefrag(url)

   *url* がフラグメント識別子を含む場合、フラグメント識別子を持たない
   バージョンに修正された *url* と、別の文字列に分割されたフラグメント
   識別子を返します。*url* 中にフラグメント識別子がない場合、そのまま
   の *url* と空文字列を返します。

   戻り値は *名前付きタプル* で、インデックスによってもしくは名前属性
   として要素にアクセスできます:

   +--------------------+---------+---------------------------+------------------------+
   | 属性               | インデ  | 値                        | 指定されなかった場合の |
   |                    | ックス  |                           | 値                     |
   |====================|=========|===========================|========================|
   | "url"              | 0       | フラグメントのない URL    | 空文字列               |
   +--------------------+---------+---------------------------+------------------------+
   | "fragment"         | 1       | フラグメント識別子        | 空文字列               |
   +--------------------+---------+---------------------------+------------------------+

   結果オブジェクトのより詳しい情報は 構造化された解析結果 節を参照し
   てください。

   バージョン 3.2 で変更: 結果はシンプルな 2 要素のタプルから構造化オ
   ブジェクトに変更されました。

urllib.parse.unwrap(url)

   Extract the url from a wrapped URL (that is, a string formatted as
   "<URL:scheme://host/path>", "<scheme://host/path>",
   "URL:scheme://host/path" or "scheme://host/path"). If *url* is not
   a wrapped URL, it is returned without changes.


URL parsing security
====================

The "urlsplit()" and "urlparse()" APIs do not perform **validation**
of inputs.  They may not raise errors on inputs that other
applications consider invalid.  They may also succeed on some inputs
that might not be considered URLs elsewhere.  Their purpose is for
practical functionality rather than purity.

Instead of raising an exception on unusual input, they may instead
return some component parts as empty strings. Or components may
contain more than perhaps they should.

We recommend that users of these APIs where the values may be used
anywhere with security implications code defensively. Do some
verification within your code before trusting a returned component
part.  Does that "scheme" make sense?  Is that a sensible "path"?  Is
there anything strange about that "hostname"?  etc.


ASCII エンコードバイト列の解析
==============================

URL を解析する関数は元々文字列のみ操作するよう設計されていました。実際
のところ、それは URL が正しくクオートされエンコードされた ASCII バイト
列を操作できた方が有用でした。結果的にこのモジュールの URL 解析関数は
すべて "bytes" および "bytearray" オブジェクトに加えて "str" オブジェ
クトでも処理するようになりました。

"str" データが渡された場合、戻り値は "str" データのみを含んだものにな
ります。"bytes" あるいは "bytearray" が渡された場合、戻り値は "bytes"
データのみを含んだものになります。

単一の関数を呼び出す時に "bytes" または "bytearray" が混在した "str"
を渡した場合、"TypeError" が、非 ASCII バイト値が渡された場合
"UnicodeDecodeError" が送出されます。

"str" と "bytes" 間で容易に変換を行えるよう、すべての URL 解析関数は
"encode()" メソッド (結果に "str" データが含まれる時用) か "decode()"
メソッド (結果に "bytes" データが含まれる時用) のどちらかを提供してい
ます。これらメソッドの動作は対応する "str" と "bytes" メソッドが持つも
のと同じです (ただしデフォルトのエンコーディングは "'utf-8'" ではなく
"'ascii'" になります)。それぞれは "encode()" メソッドを持つ "bytes" デ
ータか "decode()" メソッドを持つ "str" データのどちらかに対応した型を
生成します。

非 ASCII データを含むなど、不適切にクオートされた URL を操作する可能性
のあるアプリケーションでは、URL 解析メソッドを呼び出す前に独自にバイト
列から文字列にデコードする必要があります。

この項で説明された挙動は URL 解析関数にのみ該当します。URL クオート関
数でバイトシーケンスを生成もしくは消化する際には、別にURL クオート関数
の項で詳説されている通りのルールに従います。

バージョン 3.2 で変更: URL 解析関数は ASCII エンコードバイトシーケンス
も受け付けるようになりました


構造化された解析結果
====================

"urlparse()"、"urlsplit()"、および "urldefrag()" 関数が返すオブジェク
トは "tuple" 型のサブクラスになります。これらサブクラスにはそれぞれの
関数で説明されている属性が追加されており、前述のとおりエンコーディング
とデコーディングをサポートしています:

urllib.parse.SplitResult.geturl()

   オリジナルの URL を再結合した場合は文字列で返されます。これはスキー
   ムが小文字に正規化されていたり、空の構成要素が除去されるなど、オリ
   ジナルの URL とは異なる場合があります。特に、空のパラメータ、クエリ
   、およびフラグメント識別子は削除されます。

   "urldefrag()" の戻り値では、空のフラグメント識別子のみ削除されます
   。"urlsplit()" および "urlparse()" の戻り値では、このメソッドが返す
   URL には説明されているすべての変更が加えられます。

   加えた解析関数を逆に行えばこのメソッドの戻り値は元の URL になります
   :

   >>> from urllib.parse import urlsplit
   >>> url = 'HTTP://www.Python.org/doc/#'
   >>> r1 = urlsplit(url)
   >>> r1.geturl()
   'http://www.Python.org/doc/'
   >>> r2 = urlsplit(r1.geturl())
   >>> r2.geturl()
   'http://www.Python.org/doc/'

以下のクラスは "str" オブジェクトを操作した場合、構造化された解析結果
の実装を提供します:

class urllib.parse.DefragResult(url, fragment)

   "urldefrag()" の具象クラスの結果には "str" データが含まれます。
   "encode()" メソッドは "DefragResultBytes" インスタンスを返します。

   バージョン 3.2 で追加.

class urllib.parse.ParseResult(scheme, netloc, path, params, query, fragment)

   "urlparse()" の具象クラスの結果には "str" データが含まれます。
   "encode()" メソッドは "ParseResultBytes" インスタンスを返します。

class urllib.parse.SplitResult(scheme, netloc, path, query, fragment)

   "urlsplit()" の具象クラスの結果には "str" データが含まれます。
   "encode()" メソッドは "SplitResultBytes" インスタンスを返します。

以下のクラスは "bytes" または "bytearray" オブジェクトを操作した時に解
析結果の実装を提供します:

class urllib.parse.DefragResultBytes(url, fragment)

   "urldefrag()" の具象クラスの結果には "bytes" データが含まれます。
   "decode()" メソッドは "DefragResult" インスタンスを返します。

   バージョン 3.2 で追加.

class urllib.parse.ParseResultBytes(scheme, netloc, path, params, query, fragment)

   "urlparse()" の具象クラスの結果には "bytes" が含まれます。
   "decode()" メソッドは "ParseResult" インスタンスを返します。

   バージョン 3.2 で追加.

class urllib.parse.SplitResultBytes(scheme, netloc, path, query, fragment)

   "urlsplit()" の具象クラスの結果には "bytes" データが含まれます。
   "decode()" メソッドは "SplitResult" インスタンスを返します。

   バージョン 3.2 で追加.


URL のクオート
==============

URL クオート関数は、プログラムデータを取り URL 構成要素として使用でき
るよう特殊文字をクオートしたり非 ASCII 文字を適切にエンコードすること
に焦点を当てています。これらは上述の URL 解析関数でカバーされていない
URL 構成要素からオリジナルデータの再作成もサポートしています。

urllib.parse.quote(string, safe='/', encoding=None, errors=None)

   *string* 内の特殊文字を "%xx" を使用してエスケープします。文字、数
   字、および "'_.-~'" はクオートされません。デフォルトでは、この関数
   は URL のパス部分のクオートのために用意されています。任意のパラメー
   タ *safe* を指定すると、指定した ASCII 文字もクオートされません。デ
   フォルトは "'/'" です。

   *string* に使用できるのは "str" か "bytes" オブジェクトです。

   バージョン 3.7 で変更: Moved from **RFC 2396** to **RFC 3986** for
   quoting URL strings. "~" is now included in the set of unreserved
   characters.

   任意のパラメータ *encoding* と *errors* は "str.encode()" で受け付
   けられる非 ASCII 文字への対処法を指定します。*encoding* のデフォル
   トは "'utf-8'"、*errors* のデフォルトは "'strict'" で、非サポート文
   字があると "UnicodeEncodeError" を送出します。*string* が "bytes"
   の場合 *encoding* と *errors* を指定してはいけません。指定すると
   "TypeError" が送出されます。

   "quote(string, safe, encoding, errors)" は
   "quote_from_bytes(string.encode(encoding, errors), safe)" と等価で
   あることに留意してください。

   例: "quote('/El Niño/')" は "'/El%20Ni%C3%B1o/'" を返します。

urllib.parse.quote_plus(string, safe='', encoding=None, errors=None)

   Like "quote()", but also replace spaces with plus signs, as
   required for quoting HTML form values when building up a query
   string to go into a URL. Plus signs in the original string are
   escaped unless they are included in *safe*.  It also does not have
   *safe* default to "'/'".

   例: "quote_plus('/El Niño/')" は "'%2FEl+Ni%C3%B1o%2F'" を返します
   。

urllib.parse.quote_from_bytes(bytes, safe='/')

   "quote()" と似ていますが、"str" ではなく "bytes" オブジェクトを取り
   、文字列からバイト列へのエンコードを行いません。

   例: "quote_from_bytes(b'a&\xef')" は "'a%26%EF'" を返します。

urllib.parse.unquote(string, encoding='utf-8', errors='replace')

   エスケープされた "%xx" をそれに対応した単一文字に置き換えます。オプ
   ション引数の *encoding* と *errors* は "bytes.decode()" メソッドで
   受け付けられるパーセントエンコードされたシーケンスから Unicode 文字
   へのデコード法を指定します。

   *string* に使用できるのは "str" か "bytes" オブジェクトです。

   *encoding* のデフォルトは "'utf-8'"、*errors* のデフォルトは
   "'replace'" で、不正なシーケンスはプレースホルダー文字に置き換えら
   れます。

   例: "unquote('/El%20Ni%C3%B1o/')" は "'/El Niño/'" を返します。

   バージョン 3.9 で変更: *string* parameter supports bytes and str
   objects (previously only str).

urllib.parse.unquote_plus(string, encoding='utf-8', errors='replace')

   "unquote()" と似ていますが、HTML フォームの値のアンクオートのために
   「+」を空白に置き換えます。

   *string* は "str" でなければなりません。

   例: "unquote_plus('/El+Ni%C3%B1o/')" は "'/El Niño/'" を返します。

urllib.parse.unquote_to_bytes(string)

   スケープされた "%xx" をそれに対応した 1 オクテットに置き換え、
   "bytes" オブジェクトを返します。

   *string* に使用できるのは "str" か "bytes" オブジェクトです。

   "str" だった場合、*string* 内のエスケープされていない非 ASCII 文字
   は UTF-8 バイト列にエンコードされます。

   例: "unquote_to_bytes('a%26%EF')" は "b'a&\xef'" を返します。

urllib.parse.urlencode(query, doseq=False, safe='', encoding=None, errors=None, quote_via=quote_plus)

   マッピング型オブジェクトまたは 2 個の要素からなるタプルのシーケンス
   ("str" か "bytes" オブジェクトが含まれているかもしれません) を、パ
   ーセントエンコードされた ASCII 文字列に変換します。戻り値の文字列が
   "urlopen()" 関数での POST 操作の *data* で使用される場合はバイト列
   にエンコードしなければなりません。そうでない場合は "TypeError" が送
   出されます。

   戻り値は "'&'" 文字で区切られた "key=value" のペアからなる一組の文
   字列になります。 *key* と *value* は *quote_via* を使用してクオート
   されます。デフォルトで、値をクォートするために "quote_plus()" が使
   用されます。つまり、スペースは "'+'" 文字に、 '/' 文字は "%2F" にク
   ォートされます。これは GET リクエストの標準に準拠します
   ("application/x-www-form-urlencoded")。 *quote_via* として渡すこと
   ができる別の関数は "quote()" です。それはスペースを "%20" にエンコ
   ードし、 '/' をエンコードしません。何がクォートされるかを最大限コン
   トロールしたければ、 "quote" を使って *safe* に値を指定してください
   。

   引数 *query* が 2 要素のタプルのシーケンスの場合、各タプルの第一要
   素はキーに、第二要素は値になります。 値となる要素はシーケンスを取る
   こともでき、この場合、オプションのパラメーター *doseq* が "True" と
   評価されるのであれば、キーに対し値シーケンスの各要素を個別に結び付
   けた "key=value" のペアを、 "'&'" 文字でつないだものを生成します。
   エンコードされた文字列内のパラメーターの順序はシーケンス内のパラメ
   ータータプルの順序と一致します。

   *safe*, *encoding*, および *errors* パラメータは *quote_via* にその
   まま渡されます (クエリ要素が "str" の場合は、 *encoding* と
   *errors* パラメータだけが渡されます)。

   このエンコード処理の逆を行うには、このモジュールで提供されている
   "parse_qs()" と "parse_qsl()" を使用して、クエリ文字列を Python デ
   ータ構造に変換できます。

   POST リクエストのデータ、あるいは URL クエリ文字列を生成するために
   、 "urllib.parse.urlencode()" メソッドをどのように使えばよいかを見
   るには、urllib の使用例 を参照してください。

   バージョン 3.2 で変更: *query* はバイト列と文字列オブジェクトをサポ
   ートします。

   バージョン 3.5 で追加: *quote_via* 引数。

参考:

  WHATWG -  URL Living standard
     Working Group for the URL Standard that defines URLs, domains, IP
     addresses, the application/x-www-form-urlencoded format, and
     their API.

  **RFC 3986** - Uniform Resource Identifiers
     これが現在の標準規格 (STD66) です。urllib.parse モジュールに対す
     るすべての変更はこの規格に準拠していなければなりませんが、若干の
     逸脱はありえます。これは主には後方互換性のため、また主要なブラウ
     ザで一般的に見られる、URL を解析する上でのいくつかの事実上の要件
     を満たすためです。

  **RFC 2732** - Format for Literal IPv6 Addresses in URL's.
     この規格は IPv6 の URL を解析するときの要求事項を記述しています。

  **RFC 2396** - Uniform Resource Identifiers (URI): Generic Syntax
     この RFC では Uniform Resource Name (URN) と Uniform Resource
     Locator (URL) の両方に対する一般的な文法的要求事項を記述していま
     す。

  **RFC 2368** - The mailto URL scheme.
     mailto URL スキームに対する文法的要求事項です。

  **RFC 1808** - Relative Uniform Resource Locators
     この RFC には絶対 URL と相対 URL を結合するための規則がボーダケー
     スの取扱い方を決定する "異常な例" つきで収められています。

  **RFC 1738** - Uniform Resource Locators (URL)
     この RFC では絶対 URL の形式的な文法と意味付けを仕様化しています
     。
