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

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

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

The "webbrowser" module provides a high-level interface to allow
displaying web-based documents to users. Under most circumstances,
simply calling the "open()" function from this module will do the
right thing.

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上でリモートブラ
ウザが利用可能でない場合、制御プロセスは新しいブラウザを立ち上げ、待ち
ます。

On iOS, the "BROWSER" environment variable, as well as any arguments
controlling autoraise, browser preference, and new tab/window creation
will be ignored. Web pages will *always* be opened in the user's
preferred browser, in a new tab, with the browser being brought to the
foreground. The use of the "webbrowser" module on iOS requires the
"ctypes" module. If "ctypes" isn't available, calls to "open()" will
fail.


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

**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 controller objects
==========================

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