
:mod:`webbrowser` --- 便利なウェブブラウザコントローラー
========================================================

.. module:: webbrowser
   :synopsis: ウェウブブラウザーのための使い易いコントローラー
.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>


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

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

環境変数 :envvar:`BROWSER` が存在するならプラットフォームのデフォ
ルトであるブラウザのリストをオーバーライドし、 :data:`os.pathsep` で区切られたリストの順にブラウザの起動を試みます。
リストの中の値に ``%s`` が含まれていたら、テキストモードのブラウザのコマンドラインとして ``%s`` の代わりにURLが引数として解釈されます；
もし ``%s`` が含まれなければ、起動するブラウザの名前として単純に解釈されます。 [1]_

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

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

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


.. exception:: Error

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

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


.. function:: open(url[, new=0[, autoraise=True]])

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

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

   .. versionchanged:: 2.5
      *new* を 2 にもできるようになりました.


.. function:: open_new(url)

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


.. function:: open_new_tab(url)

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

   .. versionadded:: 2.5


.. function:: get([name])

   ブラウザの種類 *name* のコントローラーオブジェクトを返します。もし *name* が空文字列なら、呼び出した環境に適したデフォルトブラウザのコン
   トローラーを返します。


.. function:: register(name, constructor[, instance])

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

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

いくつかの種類のブラウザがあらかじめ定義されています。このモジュールで定義されている、関数 :func:`get` に与えるブラウザの名前
と、それぞれのコントローラークラスのインスタンスを以下の表に示します。

+-----------------------+-----------------------------------------+-------+
| Type Name             | Class Name                              | Notes |
+=======================+=========================================+=======+
| ``'mozilla'``         | :class:`Mozilla('mozilla')`             |       |
+-----------------------+-----------------------------------------+-------+
| ``'firefox'``         | :class:`Mozilla('mozilla')`             |       |
+-----------------------+-----------------------------------------+-------+
| ``'netscape'``        | :class:`Mozilla('netscape')`            |       |
+-----------------------+-----------------------------------------+-------+
| ``'galeon'``          | :class:`Galeon('galeon')`               |       |
+-----------------------+-----------------------------------------+-------+
| ``'epiphany'``        | :class:`Galeon('epiphany')`             |       |
+-----------------------+-----------------------------------------+-------+
| ``'skipstone'``       | :class:`BackgroundBrowser('skipstone')` |       |
+-----------------------+-----------------------------------------+-------+
| ``'kfmclient'``       | :class:`Konqueror()`                    | \(1)  |
+-----------------------+-----------------------------------------+-------+
| ``'konqueror'``       | :class:`Konqueror()`                    | \(1)  |
+-----------------------+-----------------------------------------+-------+
| ``'kfm'``             | :class:`Konqueror()`                    | \(1)  |
+-----------------------+-----------------------------------------+-------+
| ``'mosaic'``          | :class:`BackgroundBrowser('mosaic')`    |       |
+-----------------------+-----------------------------------------+-------+
| ``'opera'``           | :class:`Opera()`                        |       |
+-----------------------+-----------------------------------------+-------+
| ``'grail'``           | :class:`Grail()`                        |       |
+-----------------------+-----------------------------------------+-------+
| ``'links'``           | :class:`GenericBrowser('links')`        |       |
+-----------------------+-----------------------------------------+-------+
| ``'elinks'``          | :class:`Elinks('elinks')`               |       |
+-----------------------+-----------------------------------------+-------+
| ``'lynx'``            | :class:`GenericBrowser('lynx')`         |       |
+-----------------------+-----------------------------------------+-------+
| ``'w3m'``             | :class:`GenericBrowser('w3m')`          |       |
+-----------------------+-----------------------------------------+-------+
| ``'windows-default'`` | :class:`WindowsDefault`                 | \(2)  |
+-----------------------+-----------------------------------------+-------+
| ``'internet-config'`` | :class:`InternetConfig`                 | \(3)  |
+-----------------------+-----------------------------------------+-------+
| ``'macosx'``          | :class:`MacOSX('default')`              | \(4)  |
+-----------------------+-----------------------------------------+-------+

Notes:

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

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

(3)
   Mac OSプラットフォームのみ；標準MacPythonモジュール :mod:`ic` を必要とします。

(4)
   Mac OS X プラットフォームのみ。

簡単な例を示します。 ::

   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)


.. _browser-controllers:

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

ブラウザコントローラーには以下のメソッドが定義されていて、モジュールレベルの便利な 3 つの関数に相当します:


.. method:: controller.open(url[, new=0[, autoraise=True]])

   このコントローラーでハンドルされたブラウザで *url* を表示します。 *new* が 1 なら、可能であればブラウザの新しいウィンドウが開きます。 *new* が
   2 なら、可能であればブラウザの新しいページ(「タブ」)が開きます。


.. method:: controller.open_new(url)

   可能であれば、このコントローラーでハンドルされたブラウザの新しいウィンドウで *url* を開きますが、そうでない場合はブラウザのただ１つのウィンドウで
   *url* を開きます。 :func:`open_new` の別名。


.. method:: controller.open_new_tab(url)

   可能であれば、このコントローラーでハンドルされたブラウザの新しいページ(「タブ」)で *url* を開きますが、そうでない場合は :func:`open_new`
   と同じです。

   .. versionadded:: 2.5


.. rubric:: Footnotes

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