21.8. `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 のクオートを行う関数を定義しています。以下にこれらの詳細を説明します。

21.8.1. URL の解析¶

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

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

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

>>> from urllib.parse import urlparse
>>> o = urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')
>>> o   # doctest: +NORMALIZE_WHITESPACE
ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='', query='', fragment='')
>>> o.scheme
'http'
>>> o.port
80
>>> o.geturl()
'http://www.cwi.nl:80/%7Eguido/Python.html'

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 は空文字に設定されます。

戻り値は実際には tuple のサブクラスのインスタンスです。このクラスには以下の読み出し専用の便利な属性が追加されています:

属性	インデックス	値	指定されなかった場合の値
`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 を送出します。

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

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

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

urllib.parse.parse_qs(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace')¶

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

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

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

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

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

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

urllib.parse.parse_qsl(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace')¶

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

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

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

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

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

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

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 要素のタプル: (アドレススキーム、ネットワーク上の位置、パス、クエリ、フラグメント識別子) を返します。

戻り値は実際には tuple のサブクラスのインスタンスです。このクラスには以下の読み出し専用の便利な属性が追加されています:

属性	インデックス	値	指定されなかった場合の値
`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 を送出します。

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

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 と空文字列を返します。

戻り値は実際には tuple のサブクラスのインスタンスです。このクラスには以下の読み出し専用の便利な属性が追加されています:

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

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

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

21.8.2. 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 エンコードバイトシーケンスも受け付けるようになりました

21.8.3. 構造化された解析結果¶

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 で追加.

21.8.4. URL のクオート¶

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

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

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

string に使用できるのは str か bytes です。

任意のパラメータ 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)¶

quote() と似ていますが、クエリ文字列を URL に挿入する時のために HTML フォームの値の空白をプラス記号「+」に置き換えます。オリジナルの文字列に「+」が存在した場合は safe に指定されている場合を除きエスケープされます。safe にデフォルト値は設定されていません。

例: 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 でなければなりません。

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

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

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 クエリ文字列を生成するために、urlencode メソッドをどのように使えばよいかを見るには、urllib の使用例を参照してください。

バージョン 3.2 で変更: クエリ文字列にバイト列と文字列オブジェクトをサポートしました。

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

参考

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 の形式的な文法と意味付けを仕様化しています。

関連キーワード: 　urllib, 解析, bytes, 要素, メソッド, scheme, encoding, errors, データ, quote

21.8. `urllib.parse` --- URL を解析して構成要素にする¶

21.8.1. URL の解析¶

21.8.2. ASCII エンコードバイト列の解析¶

21.8.3. 構造化された解析結果¶

21.8.4. URL のクオート¶

Table of Contents

前のトピックへ

次のトピックへ

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

21.8.1. URL の解析¶

21.8.2. ASCII エンコードバイト列の解析¶

21.8.3. 構造化された解析結果¶

21.8.4. URL のクオート¶

21.8. `urllib.parse` --- URL を解析して構成要素にする¶