ノート
urlparse モジュールは Python 3 では urllib.parse にリネームされました。 2to3 ツールはソースコードのimportを自動的に Python 3 用に修正します。
このモジュールでは URL (Uniform Resource Locator) 文字列をその構成要素 (アドレススキーム、ネットワーク上の位置、パスその他) に分解したり、構成要素を URL に組みなおしたり、”相対 URL (relative URL)” を指定した “基底 URL (base URL)” に基づいて絶対 URL に変換するための標準的なインタフェースを定義しています。
このモジュールは相対 URL のインターネット RFC に対応するように設計されました (そして 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 。
バージョン 2.5 で追加: sftp および sips スキームのサポートが追加されました.
urlparse モジュールには以下の関数が定義されています:
URL を解釈して 6 つの構成要素にし、6 要素のタプルを返します。このタプルは URL の一般的な構造: scheme://netloc/path;parameters?query#fragment に対応しています。 各タプル要素は文字列で、空の場合もあります。構成要素がさらに小さい要素に分解されることはありません (例えば ネットワーク上の位置は単一の文字列になります)。また % によるエスケープは展開されません。上で示された区切り文字がタプルの各要素の一部分 として含まれることはありませんが、 path 要素の先頭のスラッシュがある場合には例外です。たとえば以下のようになります。
>>> from urlparse import urlparse
>>> o = urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')
>>> o
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'
default_scheme 引数が指定されている場合、標準のアドレススキームを表し、アドレススキームを指定していない URL に対してのみ 使われます。この引数の標準の値は空文字列です。
allow_fragments 引数が偽の場合、URL のアドレススキームがフラグメント指定をサポートしていても指定できなくなります。 この引数の標準の値は True です。
戻り値は実際には tuple のサブクラスのインスタンスです。このクラスには以下の読み出し専用の便利な属性が追加されています。
属性 | インデクス | 値 | 指定されなかった場合の値 |
---|---|---|---|
scheme | 0 | URL スキーム | 空文字列 |
netloc | 1 | ネットワーク上の位置 | 空文字列 |
path | 2 | 階層的パス | 空文字列 |
params | 3 | 最後のパス要素に対するパラメータ | 空文字列 |
query | 4 | クエリ要素 | 空文字列 |
fragment | 5 | フラグメント指定子 | 空文字列 |
username | ユーザ名 | None | |
password | パスワード | None | |
hostname | ホスト名 (小文字) | None | |
port | ポート番号を表わす整数 (もしあれば) | None |
結果オブジェクトのより詳しい情報は urlparse() および urlsplit() の結果 節を参照してください。
バージョン 2.5 で変更: 戻り値に属性が追加されました.
文字列引数として渡されたクエリ文字列 (application/x-www-form-urlencoded 型のデータ) を解釈します。解釈されたデータを辞書として返します。 辞書のキーは一意なクエリ変数名で、値は各変数名に対する値からなるリストです。
オプションの引数 keep_blank_values は、 URL エンコードされたクエリ中で値の入っていないものを空文字列と見なすかどうか を示すフラグです。値が真であれば、値の入っていないフィールドは空文字列のままになります。標準では偽で、値の入っていない フィールドを無視し、そのフィールドはクエリに含まれていないものとして扱います。
オプションの引数 strict_pasing はパース時のエラーをどう扱うかを決めるフラグです。値が偽なら (標準の設定です)、 エラーは暗黙のうちに無視します。値が真なら ValueError 例外を送出します。
辞書等をクエリ文字列に変換する場合は urllib. urlencode() 関数を使用してください。
文字列引数として渡されたクエリ文字列 (application/x-www-form-urlencoded 型のデータ) を 解釈します。解釈されたデータは名前と値のペアからなるリストです。
オプションの引数 keep_blank_values は、 URL エンコードされたクエリ中で値の入っていないものを空文字列と見なすかどうか を示すフラグです。値が真であれば、値の入っていないフィールドは空文字列のままになります。標準では偽で、値の入っていない フィールドを無視し、そのフィールドはクエリに含まれていないものとして扱います。
オプションの引数 strict_pasing はパース時のエラーをどう扱うかを決めるフラグです。値が偽なら (標準の設定です)、 エラーは暗黙のうちに無視します。値が真なら ValueError 例外を送出します。
ペアのリストからクエリ文字列を生成する場合には urllib.urlencode() 関数を使用します。
urlparse() が返すような形式のタプルから URL を構築します。 parts 引数は任意の 6 要素イテラブルです。 解析された元の URL が、不要な区切り文字を持っていた場合には、多少違いはあるが等価な URL になるかもしれません。 (例えばクエリ内容が空の ? のようなもので、RFC はこれらを等価だと述べています。)
urlparse() に似ていますが、URL から params を切り離しません。このメソッドは通常、URL の path 部分において、各セグメントにパラメタ指定をできるようにした最近の URL 構文 (RFC 2396 参照) が必要な 場合に、 urlparse() の代わりに使われます。パスセグメントとパラメタを分割するためには分割用の関数が必要です。この関数は 5 要素のタプル: (アドレススキーム、ネットワーク上の位置、パス、クエリ、フラグメント指定子) を返します。
戻り値は実際には tuple のサブクラスのインスタンスです。このクラスには以下の読み出し専用の便利な属性が追加されています。
属性 | インデクス | 値 | 指定されなかった場合の値 |
---|---|---|---|
scheme | 0 | URL スキーム | 空文字列 |
netloc | 1 | ネットワーク上の位置 | 空文字列 |
path | 2 | 階層的パス | 空文字列 |
query | 3 | クエリ要素 | 空文字列 |
fragment | 4 | フラグメント指定子 | 空文字列 |
username | ユーザ名 | None | |
password | パスワード | None | |
hostname | ホスト名 (小文字) | None | |
port | ポート番号を表わす整数 (もしあれば) | None |
結果オブジェクトのより詳しい情報は urlparse() および urlsplit() の結果 節を参照してください。
バージョン 2.2 で追加.
バージョン 2.5 で変更: 戻り値に属性が追加されました.
urlsplit() が返すような形式のタプル中のエレメントを組み合わせて、文字列の完全な URL にします。 parts 引数は任意の 5 要素イテラブルです。解析された元の URL が、不要な区切り文字を持っていた場合には、多少違いはあるが等価な URL になるかもしれません。 (例えばクエリ内容が空の ? のようなもので、RFC はこれらを等価だと述べています。)
バージョン 2.2 で追加.
“基底 URL”(base)と別のURL(url)を組み合わせて、完全な URL (“絶対 URL”) を構成します。 ぶっちゃけ、この関数は基底 URL の要素、特にアドレススキーム、ネットワーク上の位置、およびパス (の一部) を使って、相対 URL に ない要素を提供します。以下の例のようになります。
>>> from urlparse 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 を削除してください。
url がフラグメント指定子を含む場合、フラグメント指定子を持たないバージョンに修正された url と、別の文字列に分割 されたフラグメント指定子を返します。 url 中にフラグメント指定子がない場合、そのままの url と空文字列を返します。
参考
urlparse() および urlsplit() から得られる結果オブジェクトはそれぞれ tuple 型のサブクラスです。これらのクラスはそれぞれの関数の説明の中で述べたような属性とともに、追加のメソッドを一つ提供しています。
再結合された形で元の URL の文字列を返します。この文字列は元の URL とは次のような点で異なるかもしれません。スキームは常に小文字に正規化されます。 また空の要素は省略されます。特に、空のパラメータ、クエリ、フラグメント識別子は取り除かれます。
このメソッドの結果は再び解析に回されたとしても不動点となります。
>>> import urlparse
>>> url = 'HTTP://www.Python.org/doc/#'
>>> r1 = urlparse.urlsplit(url)
>>> r1.geturl()
'http://www.Python.org/doc/'
>>> r2 = urlparse.urlsplit(r1.geturl())
>>> r2.geturl()
'http://www.Python.org/doc/'
バージョン 2.5 で追加.
以下のクラスが解析結果の実装を提供します。
具体的な結果クラスたちの基底クラスです。このクラスがほとんどの属性の定義を与えます。しかし geturl() メソッドは提供しません。この クラスは tuple から派生していますが、 __init__() や __new__() をオーバーライドしませ ん。
urlparse() の結果のための具体クラスです。 __new__() メソッドをオーバーライドして正しい個数の引数が 引き渡されたことを確認するようにしています。
urlsplit() の結果のための具体クラスです。 __new__() メソッドをオーバーライドして正しい個数の引数が 引き渡されたことを確認するようにしています。