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

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

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

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

指定されなかった場合の値
最後のパス要素に対するパラメータ
ポート番号を表わす整数 (もしあれば)

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

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

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

バージョン 3.3 で変更: に従い、fragment はすべての URL スキームに対して解析されるようになりました

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

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

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

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

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

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

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

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

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

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

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

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

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

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

指定されなかった場合の値
ポート番号を表わす整数 (もしあれば)

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

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

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

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

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

allow_fragments 引数は における引数と同じ意味とデフォルトを持ちます

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

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

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

指定されなかった場合の値
フラグメントのない URL

結果オブジェクトのより詳しい情報は 節を参照してください。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

バージョン 3.2 で追加.

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

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

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

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

バージョン 3.2 で追加.

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

バージョン 3.2 で追加.

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

バージョン 3.2 で追加.

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

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

を指定してはいけません指定すると が送出されます。

safe) と等価であることに留意してください

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

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

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

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

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

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

string は でなければなりません

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

string に使用できるのは か です

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

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

戻り値は '&' 文字で区切られた key=value のペアからなる一組の文字列になります。 key と value は unquotee_via を使用してクオートされますデフォルトで、値をクォートするために unquotee_via として渡すことができる別の関数は です。それはスペースを %20 にエンコードし、 '/' をエンコードしません何がクォートされるかを最大限コントロールしたければ、 unquotee を使って safe に値を指定してください。

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

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

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

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