# 17 `urlparse` -- URL を解析して構成要素にする

このモジュールでは 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` モジュールには以下の関数が定義されています:

`urlparse`( | urlstring[, default_scheme[, allow_fragments]])

  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
      ('http', 'www.cwi.nl:80', '/%7Eguido/Python.html', '', '', '')
      >>> 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`

  結果オブジェクトのより詳しい情報は18.17.1節 ```urlparse()` および `urlsplit()` の結果'' を参照してください。

  バージョン 2.5 で 変更 された仕様: 戻り値に属性が追加されました

`urlunparse`( | parts)

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

`urlsplit`( | urlstring[, default_scheme[, allow_fragments]])

  `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`

  結果オブジェクトのより詳しい情報は18.17.1節 ```urlparse()` および `urlsplit()` の結果'' を参照してください。

  バージョン 2.2 で 新たに追加 された仕様です。 バージョン 2.5 で 変更 された仕様: 戻り値に属性が追加されました

`urlunsplit`( | parts)

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

`urljoin`( | base, url[, allow_fragments])

  ``基底 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()` における引数と同じ意味 とデフォルトを持ちます。

`urldefrag`( | url)

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

参考:

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

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

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