"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"

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

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

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

3. Only on macOS platform.

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

簡単な例を示します:

   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 つの関数に相当します:

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