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

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

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

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 part does not contain %s, it is simply interpreted as the name of the browser to launch. [1]

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

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

Command-line interface

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)

'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/'

# ブラウザウィンドウがすでに開いていれば、新しいタブで URL を開く。
webbrowser.open_new_tab(url)

# 新しいウィンドウで URL を開き、可能なら前面に表示する。
webbrowser.open_new(url)

Browser controller objects

ブラウザコントローラーは 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() と同じです。

脚注