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