# 20.1. `webbrowser` --- 便利なウェブブラウザコントローラー

ソースコード: Lib/webbrowser.py

`webbrowser` モジュールにはウェブベースのドキュメントを表示するための、とてもハイレベルなインターフェースが定義されています。たいていの環境では、このモジュールの `open()` を呼び出すだけで正しく動作します。

Unixでは、X11上でグラフィカルなブラウザが選択されますが、グラフィカルなブラウザが利用できなかったり、X11が利用できない場合はテキストモードのブラウザが使われます。もしテキストモードのブラウザが使われたら、ユーザがブラウザから抜け出すまでプロセスの呼び出しはブロックされます。

環境変数 `BROWSER` が存在する場合、プラットフォームのデフォルトであるブラウザのリストをオーバーライドし、 `os.pathsep` で区切られたリストの順にブラウザの起動を試みます。リストの中の値に `%s` が含まれていたら、テキストモードのブラウザのコマンドラインとして `%s` の代わりにURLが引数として解釈されます; もし `%s` が含まれなければ、起動するブラウザの名前として単純に解釈されます。 [1]

非UnixプラットフォームあるいはUnix上でリモートブラウザが利用可能な場合、制御プロセスはユーザがブラウザを終了するのを待ちませんが、ディスプレイにブラウザのウィンドウを表示させたままにします。Unix上でリモートブラウザが利用可能でない場合、制御プロセスは新しいブラウザを立ち上げ、待ちます。

webbrowser スクリプトをこのモジュールのコマンドライン・インタフェースとして使うことができます。スクリプトは引数に 1 つの URL を受け付けます。また次のオプション引数を受け付けます。 `-n` により可能ならば新しいブラウザウィンドウで指定された URL を開きます。一方、 `-t` では新しいブラウザのページ (「タブ」) で開きます。 当然ながらこれらのオプションは排他的です。使用例は次の通りです:

    python -m webbrowser -t "http://www.python.org"

以下の例外が定義されています:

exception `webbrowser.``Error`

  ブラウザのコントロールエラーが起こると発生する例外。

以下の関数が定義されています:

`webbrowser.``open`(url, new=0, autoraise=True)

  デフォルトのブラウザで url を表示します。new が 0 なら、url はブラウザの今までと同じウィンドウで開きます。new が 1 なら、可能であればブラウザの新しいウィンドウが開きます。new が 2 なら、可能であればブラウザの新しいタブが開きます。autoraise が `True` なら、可能であればウィンドウが前面に表示されます（多くのウィンドウマネージャではこの変数の設定に関わらず、前面に表示されます）。

  幾つかのプラットフォームにおいて、ファイル名をこの関数で開こうとすると、OSによって関連付けられたプログラムが起動されます。しかし、この動作はポータブルではありませんし、サポートされていません。

  バージョン 2.5 で変更: new を 2 にもできるようになりました.

`webbrowser.``open_new`(url)

  可能であれば、デフォルトブラウザの新しいウィンドウで url を開きますが、そうでない場合はブラウザのただ１つのウィンドウで url を開きます。

`webbrowser.``open_new_tab`(url)

  可能であれば、デフォルトブラウザの新しいページ(「タブ」)で url を開きますが、そうでない場合は `open_new()` と同様に振る舞います。

  バージョン 2.5 で追加.

`webbrowser.``get`([name])

  ブラウザの種類 name のコントローラーオブジェクトを返します。もし name が空文字列 なら、呼び出した環境に適したデフォルトブラウザのコントローラーを返します。

`webbrowser.``register`(name, constructor[, instance])

  ブラウザの種類 name を登録します。ブラウザの種類が登録されたら、 `get()` でそのブラウザのコントローラーを呼び出すことができます。 instance が指定されなかったり、 `None` なら、インスタンスが必要な時には constructor がパラメータなしに呼び出されて作られます。 instance が指定されたら、 constructor は呼び出されないので、 `None` でかまいません。

  この登録は、変数 `BROWSER` を設定するか、 `get()` を空文字列でなく、宣言したハンドラの名前と一致する引数とともに呼び出すときだけ、役に立ちます。

いくつかの種類のブラウザがあらかじめ定義されています。このモジュールで定義されている、関数 `get()` に与えるブラウザの名前と、それぞれのコントローラークラスのインスタンスを以下の表に示します。

Type Name | Class Name | 注釈
--- | --- | ---
`'mozilla'` | `Mozilla('mozilla')` |
`'firefox'` | `Mozilla('mozilla')` |
`'netscape'` | `Mozilla('netscape')` |
`'galeon'` | `Galeon('galeon')` |
`'epiphany'` | `Galeon('epiphany')` |
`'skipstone'` | `BackgroundBrowser('skipstone')` |
`'kfmclient'` | `Konqueror()` | (1)
`'konqueror'` | `Konqueror()` | (1)
`'kfm'` | `Konqueror()` | (1)
`'mosaic'` | `BackgroundBrowser('mosaic')` |
`'opera'` | `Opera()` |
`'grail'` | `Grail()` |
`'links'` | `GenericBrowser('links')` |
`'elinks'` | `Elinks('elinks')` |
`'lynx'` | `GenericBrowser('lynx')` |
`'w3m'` | `GenericBrowser('w3m')` |
`'windows-default'` | `WindowsDefault` | (2)
`'macosx'` | `MacOSX('default')` | (3)
`'safari'` | `MacOSX('safari')` | (3)
`'google-chrome'` | `Chrome('google-chrome')` | (4)
`'chrome'` | `Chrome('chrome')` | (4)
`'chromium'` | `Chromium('chromium')` | (4)
`'chromium-browser'` | `Chromium('chromium-browser')` | (4)

注釈:

1. "Konqueror"はUnixのKDEデスクトップ環境のファイルマネージャで、KDEが動作している時にだけ意味を持ちます。何か信頼できる方法でKDEを検出するのがいいでしょう; 変数 `KDEDIR` では十分ではありません。また、KDE 2で konqueror コマンドを使うときにも、"kfm"が使われます --- Konquerorを動作させるのに最も良い方法が実装によって選択されます。
2. Windowsプラットフォームのみ。
3. Mac OS X プラットフォームのみ。
4. Chrome/Chromium のサポートがバージョン 2.7.5 で追加されました。

簡単な例を示します:

    url = 'http://www.python.org/'

    # Open URL in a new tab, if a browser window is already open.
    webbrowser.open_new_tab(url + 'doc/')

    # Open URL in new window, raising the window if possible.
    webbrowser.open_new(url)

## 20.1.1. ブラウザコントローラーオブジェクト

ブラウザコントローラーには以下のメソッドが定義されていて、モジュールレベルの便利な 3 つの関数に相当します:

`controller.``open`(url, new=0, autoraise=True)

  このコントローラーでハンドルされたブラウザで url を表示します。new が 1 なら、可能であればブラウザの新しいウィンドウが開きます。new が 2 なら、可能であればブラウザの新しいページ(「タブ」)が開きます。

`controller.``open_new`(url)

  可能であれば、このコントローラーでハンドルされたブラウザの新しいウィンドウで url を開きますが、そうでない場合はブラウザのただ１つのウィンドウで url を開きます。 `open_new()` の別名。

`controller.``open_new_tab`(url)

  可能であれば、このコントローラーでハンドルされたブラウザの新しいページ(「タブ」)で url を開きますが、そうでない場合は `open_new()` と同じです。

  バージョン 2.5 で追加.

注記

[1] | ここでブラウザの名前が絶対パスで書かれていない場合は `PATH` 環境変数で与えられたディレクトリから探し出されます。