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

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

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

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

If the environment variable `BROWSER` exists, it is interpreted as the `os.pathsep`-separated list of browsers to try ahead of the platform defaults. When the value of a list part contains the string `%s`, then it is interpreted as a literal browser command line to be used with the argument URL substituted for `%s`; if the value is a single word that refers to one of the already registered browsers this browser is added to the front of the search list; if the part does not contain `%s`, it is simply interpreted as the name of the browser to launch. [1]

バージョン 3.14 で変更: The `BROWSER` variable can now also be used to reorder the list of platform defaults. This is particularly useful on macOS where the platform defaults do not refer to command-line tools on `PATH`.

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

iOS では、 `BROWSER` 環境変数に加えて、 autoraise 、ブラウザー設定、新しいタブ・ウィンドウの作成を操作する引数は無視されます。ウェブページは 常に ユーザーが設定したブラウザーで、新しいタブで、前面に表示されて開かれます。 iOS で `webbrowser` モジュールを使用する場合には `ctypes` モジュールが必要です。 `ctypes` が利用可能でない場合は、 `open()` の呼び出しは失敗します。

webbrowser のスクリプトは、モジュールのコマンドラインインターフェースとして利用可能です。これは引数として URL を受け入れます。また、次のオプションのパラメーターを受け入れます。

-n, --new-window

  Opens the URL in a new browser window, if possible.

-t, --new-tab

  Opens the URL in a new browser tab.

The options are, naturally, mutually exclusive. Usage example:

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

Availability: not WASI, not Android.

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

exception webbrowser.Error

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

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

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

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

  Returns `True` if a browser was successfully launched, `False` otherwise.

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

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

webbrowser.open_new(url)

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

  Returns `True` if a browser was successfully launched, `False` otherwise.

webbrowser.open_new_tab(url)

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

  Returns `True` if a browser was successfully launched, `False` otherwise.

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')` |
`'iosbrowser'` | `IOSBrowser` | (4)

注釈:

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

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

3. macOS のみ。

4. iOS のみ。

Added in version 3.2: 新しい `MacOSXOSAScript` クラスが追加され、以前の `MacOSX` に替わって Mac で使用されます。これにより、現在 OS のデフォルトとして設定されていないブラウザを開くサポートが追加されました。

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

バージョン 3.12 で変更: いくつかの古いブラウザのサポートが削除されました。削除されたブラウザには、 Grail 、 Mosaic 、 Netscape 、 Galeon 、 Skipstone 、 Iceape 、そして Firefox のバージョン 35 以前が含まれます。

バージョン 3.13 で変更: iOS のサポートが追加されました。

簡単な例を示します:

    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)

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

Browser controllers provide the `name` attribute, and the following three methods which parallel module-level convenience functions:

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