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

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

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

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

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

If the environment variable "BROWSER" exists, it is interpreted to
override the platform default list of browsers, as an
"os.pathsep"-separated list of browsers to try in order.  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 part does not contain "%s", it is simply
interpreted as the name of the browser to launch. [1]

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

**webbrowser** スクリプトをこのモジュールのコマンドライン・インタフェ
ースとして使うことができます。スクリプトは引数に 1 つの URL を受け付け
ます。また次のオプション引数を受け付けます。 "-n" により可能ならば新し
いブラウザウィンドウで指定された URL を開きます。一方、 "-t" では新し
いブラウザのページ (「タブ」) で開きます。 当然ながらこれらのオプショ
ンは排他的です。使用例は次の通りです:

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

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

exception webbrowser.Error

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

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

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

   デフォルトのブラウザで *url* を表示します。*new* が 0 なら、*url*
   はブラウザの今までと同じウィンドウで開きます。*new* が 1 なら、可能
   であればブラウザの新しいウィンドウが開きます。*new* が 2 なら、可能
   であればブラウザの新しいタブが開きます。*autoraise* が "True" なら
   、可能であればウィンドウが前面に表示されます（多くのウィンドウマネ
   ージャではこの変数の設定に関わらず、前面に表示されます）。

   幾つかのプラットフォームにおいて、ファイル名をこの関数で開こうとす
   ると、OSによって関連付けられたプログラムが起動されます。しかし、こ
   の動作はポータブルではありませんし、サポートされていません。

   バージョン 2.5 で変更: *new* can now be 2.

webbrowser.open_new(url)

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

webbrowser.open_new_tab(url)

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

   バージョン 2.5 で追加.

webbrowser.get([name])

   Return a controller object for the browser type *name*.  If *name*
   is empty, return a controller for a default browser appropriate to
   the caller’s environment.

webbrowser.register(name, constructor[, instance])

   ブラウザの種類 *name* を登録します。ブラウザの種類が登録されたら、
   "get()" でそのブラウザのコントローラーを呼び出すことができます。
   *instance* が指定されなかったり、 "None" なら、インスタンスが必要な
   時には *constructor* がパラメータなしに呼び出されて作られます。
   *instance* が指定されたら、 *constructor* は呼び出されないので、
   "None" でかまいません。

   この登録は、変数 "BROWSER" を設定するか、 "get()" を空文字列でなく
   、宣言したハンドラの名前と一致する引数とともに呼び出すときだけ、役
   に立ちます。

いくつかの種類のブラウザがあらかじめ定義されています。このモジュールで
定義されている、関数 "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'"              | "MacOSX('default')"                       | (3)     |
+-------------------------+-------------------------------------------+---------+
| "'safari'"              | "MacOSX('safari')"                        | (3)     |
+-------------------------+-------------------------------------------+---------+
| "'google-chrome'"       | "Chrome('google-chrome')"                 | (4)     |
+-------------------------+-------------------------------------------+---------+
| "'chrome'"              | "Chrome('chrome')"                        | (4)     |
+-------------------------+-------------------------------------------+---------+
| "'chromium'"            | "Chromium('chromium')"                    | (4)     |
+-------------------------+-------------------------------------------+---------+
| "'chromium-browser'"    | "Chromium('chromium-browser')"            | (4)     |
+-------------------------+-------------------------------------------+---------+

注釈:

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

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

3. Mac OS X プラットフォームのみ。

4. Support for Chrome/Chromium has been added in version 2.7.5.

簡単な例を示します:

   url = 'http://www.python.org/'

   # Open URL in a new tab, if a browser window is already open.
   webbrowser.open_new_tab(url + 'doc/')

   # 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()"
   と同じです。

   バージョン 2.5 で追加.

-[ 脚注 ]-

[1] ここでブラウザの名前が絶対パスで書かれていない場合は "PATH" 環
    境変 数で与えられたディレクトリから探し出されます。
