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

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

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

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

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

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

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

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

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

* "-n"/"--new-window" 可能なら、ブラウザーの新しいウィンドウで URL を
  開きます。

* "-t"/"--new-tab" ブラウザーの新しいページ ("タブ") で URL を開きます
  。

当然、これらのオプションは互いに排他的です。使用例:

   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)


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

ブラウザコントローラーには以下のメソッドが定義されていて、モジュールレ
ベルの便利な 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" 環境変
    数で与えられたディレクトリから探し出されます。
