# `webbrowser` --- Convenient web-browser controller

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

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

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

環境変数 `BROWSER` が存在する場合、これは `os.pathsep` で区切られたブラウザのリストとして解釈され、プラットフォームのデフォルトのブラウザリストに先立って順に試みられます。リストの中の値に `%s` が含まれていれば、 `%s` を URL に置換したコマンドライン文字列と解釈されます；もし `%s` が含まれなければ、起動するブラウザの名前として単純に解釈されます。 [1]

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

The script webbrowser can be used as a command-line interface for the module. It accepts a URL as the argument. It accepts the following optional parameters: `-n` opens the URL in a new browser window, if possible; `-t` opens the URL in a new browser page ("tab"). The options are, naturally, mutually exclusive. Usage example:

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

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms `wasm32-emscripten` and `wasm32-wasi`. See WebAssembly プラットフォーム for more information.

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

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')` |
`'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'` | `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" is the file manager for the KDE desktop environment for Unix, and only makes sense to use if KDE is running. Some way of reliably detecting KDE would be nice; the `KDEDIR` variable is not sufficient. Note also that the name "kfm" is used even when using the konqueror command with KDE 2 --- the implementation selects the best strategy for running Konqueror.

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

3. Only on macOS platform.

バージョン 3.3 で追加: Chrome/Chromium のサポートが追加されました。

バージョン 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

  ブラウザのシステム依存名。

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` 環境変数で与えられたディレクトリから探し出されます。