# `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 "https://www.python.org"

利用可能性: Emscripten でなく、WASI でもないこと。

このモジュールは WebAssembly プラットフォーム `wasm32-emscripten` と `wasm32-wasi` では動作しないか、利用不可です。詳しくは、WebAssemblyプラットフォーム を見てください。

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

exception webbrowser.Error

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

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

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

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

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

  引数 `url` を指定して 監査イベント `webbrowser.open` を送出します。

webbrowser.open_new(url)

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

webbrowser.open_new_tab(url)

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

webbrowser.get(using=None)

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

webbrowser.register(name, constructor, instance=None, *, preferred=False)

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

  preferred を `True` に設定すると、 `get()` の引数無しの呼び出しの結果が優先的にこのブラウザになります。 そうでない場合は、この関数は、変数 `BROWSER` を設定するか、 `get()` を空文字列ではない、宣言したハンドラの名前と一致する引数とともに呼び出すときにだけ、役に立ちます。

  バージョン 3.7 で変更: preferred キーワード専用引数が追加されました。

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

Type Name | Class Name | 注釈
--- | --- | ---
`'mozilla'` | `Mozilla('mozilla')` |
`'firefox'` | `Mozilla('mozilla')` |
`'epiphany'` | `Epiphany('epiphany')` |
`'kfmclient'` | `Konqueror()` | (1)
`'konqueror'` | `Konqueror()` | (1)
`'kfm'` | `Konqueror()` | (1)
`'opera'` | `Opera()` |
`'links'` | `GenericBrowser('links')` |
`'elinks'` | `Elinks('elinks')` |
`'lynx'` | `GenericBrowser('lynx')` |
`'w3m'` | `GenericBrowser('w3m')` |
`'windows-default'` | `WindowsDefault` | (2)
`'macosx'` | `MacOSXOSAScript('default')` | (3)
`'safari'` | `MacOSXOSAScript('safari')` | (3)
`'google-chrome'` | `Chrome('google-chrome')` |
`'chrome'` | `Chrome('chrome')` |
`'chromium'` | `Chromium('chromium')` |
`'chromium-browser'` | `Chromium('chromium-browser')` |

注釈:

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

2. Windowsプラットフォームのみ。

3. macOS プラットフォームのみ。

Added in version 3.3: Chrome/Chromium のサポートが追加されました。

バージョン 3.12 で変更: Support for several obsolete browsers has been removed. Removed browsers include Grail, Mosaic, Netscape, Galeon, Skipstone, Iceape, and Firefox versions 35 and below.

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: `MacOSX` is deprecated, use `MacOSXOSAScript` instead.

簡単な例を示します:

    url = 'https://docs.python.org/'

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

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

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

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

webbrowser.name

  System-dependent name for the browser.

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()` と同じです。

脚注

[1]

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