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

脚注