"webbrowser" --- 便利なウェブブラウザコントローラー
***************************************************

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

======================================================================

"webbrowser" モジュールは、ウェブ上のドキュメントをユーザーに表示する
ための高水準インターフェースを提供します。 ほとんどの場合、このモジュ
ールの "open()" 関数を呼び出すだけで適切に動作します。

Unix では、X11 上でグラフィカルなブラウザが優先されます。 グラフィカル
なブラウザや X11 のディスプレイが利用できない場合は、テキストモードの
ブラウザを使います。 テキストモードのブラウザを使う場合、ユーザーがブ
ラウザを終了するまで、呼び出し元のプロセスはブロックされます。

環境変数 "BROWSER" がある場合、その値は "os.pathsep" で区切られたブラ
ウザのリストとして解釈され、プラットフォームのデフォルトより先に試され
ます。 リストの項目に文字列 "%s" が含まれる場合は、その項目をブラウザ
のコマンドラインとして扱い、"%s" を引数の URL に置き換えて使います。
項目が登録済みブラウザのいずれかを指す単一の語であれば、そのブラウザを
検索リストの先頭に追加します。 "%s" を含まない項目は、単に起動するブラ
ウザの名前と解釈されます。 [1]

バージョン 3.14 で変更: "BROWSER" 変数で、プラットフォームのデフォルト
のリストを並べ替えることもできるようになりました。 これは特に、プラッ
トフォームのデフォルトが "PATH" 上のコマンドラインツールを指していない
macOS で役立ちます。

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

iOS では、"BROWSER" 環境変数、および前面表示、ブラウザの優先順位、新し
いタブやウィンドウの作成を制御する引数はすべて無視されます。 ウェブペ
ージは *常に* ユーザーが選んだブラウザの新しいタブで開かれ、そのブラウ
ザが前面に表示されます。 iOS で "webbrowser" モジュールを使うには
"ctypes" モジュールが必要です。 "ctypes" を利用できない場合、"open()"
の呼び出しは失敗します。


コマンドライン・インターフェース
================================

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

-n, --new-window

   可能であれば、新しいブラウザウィンドウで URL を開きます。

-t, --new-tab

   新しいブラウザタブで URL を開きます。

これらのオプションは互いに排他的です。 使用例を示します:

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

利用可能な環境: not WASI, not Android.

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

exception webbrowser.Error

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

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

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

   デフォルトのブラウザで *url* を表示します。 *new* が 0 なら、可能で
   あれば同じブラウザウィンドウで *url* を開きます。 *new* が 1 なら、
   可能であれば新しいブラウザウィンドウを開きます。 *new* が 2 なら、
   可能であれば新しいブラウザページ (「タブ」) を開きます。
   *autoraise* が "True" なら、可能であればウィンドウを前面に表示しま
   す (多くのウィンドウマネージャーでは、この値にかかわらず前面に表示
   されます)。

   ブラウザの起動に成功した場合は "True" を、それ以外は "False" を返し
   ます。

   プラットフォームによっては、この関数でファイル名を開こうとすると、
   オペレーティングシステムが関連付けたプログラムを起動できる場合があ
   ります。 ただし、この動作はサポートされておらず、移植性もありません
   。

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

webbrowser.open_new(url)

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

   ブラウザの起動に成功した場合は "True" を、それ以外は "False" を返し
   ます。

webbrowser.open_new_tab(url)

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

   ブラウザの起動に成功した場合は "True" を、それ以外は "False" を返し
   ます。

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)     |
+--------------------------+-------------------------------------------+---------+
| "'macos'"                | "MacOS('default')"                        | (3)     |
+--------------------------+-------------------------------------------+---------+
| "'safari'"               | "MacOS('safari')"                         | (3)     |
+--------------------------+-------------------------------------------+---------+
| "'chrome'"               | "MacOS('google chrome')"                  | (3)     |
+--------------------------+-------------------------------------------+---------+
| "'firefox'"              | "MacOS('firefox')"                        | (3)     |
+--------------------------+-------------------------------------------+---------+
| "'google-chrome'"        | "Chrome('google-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 のサポートが追加されました。

Added in version 3.15: "MacOSXOSAScript" の代わりとなる "MacOS" を追加
しました。 **osascript** の代わりに **/usr/bin/open** でブラウザを開き
ます。

バージョン 3.15 で非推奨、バージョン 3.17 で削除予定:
"MacOSXOSAScript" は非推奨となりました。 代わりに "MacOS" を使ってくだ
さい。 **osascript** の代わりに **/usr/bin/open** を使うことは、セキュ
リティと使いやすさの改善につながります。 **osascript** は汎用スクリプ
トインタープリタとして悪用される可能性があるため、管理対象のシステムで
はブロックされる場合があります。

簡単な例を示します:

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

   # ブラウザウィンドウがすでに開いていれば、新しいタブで URL を開く。
   webbrowser.open_new_tab(url)

   # 新しいウィンドウで URL を開き、可能なら前面に表示する。
   webbrowser.open_new(url)


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

ブラウザコントローラーは "name" 属性と、モジュールレベルの便利な関数に
対応する以下の 3 つのメソッドを提供します:

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