webbrowser --- 方便的網頁瀏覽器控制器

原始碼：Lib/webbrowser.py

webbrowser 模組提供了一個高階介面，允許向使用者顯示基於網頁的文件。在大多數情況下，只需從此模組呼叫open() 函式即可完成正確的操作。

在 Unix 下，X11 下首選圖形瀏覽器，但如果圖形瀏覽器不可用或 X11 顯示不可用，則將使用文字模式瀏覽器。如果使用文字模式瀏覽器，則呼叫程序將會阻塞 (block)，直到使用者退出瀏覽器。

如果環境變數BROWSER 存在，它會被直譯為以os.pathsep 分隔的瀏覽器串列，以在平台預設值之前嘗試。當串列部分的值包含字串%s 時，它會被直譯為字面瀏覽器命令列，並使用引數 URL 替換%s；如果該部分不包含%s，則它僅被直譯為要啟動的瀏覽器的名稱。[1]

對於非 Unix 平台，或當 Unix 上有可用的遠端瀏覽器時，控制行程不會等待使用者以完成瀏覽器，而是允許遠端瀏覽器在顯示器上維護自己的視窗。如果遠端瀏覽器在 Unix 上不可用，控制行程將啟動新的瀏覽器並等待。

在 iOS 上，BROWSER 環境變數以及控制自動引發 (autoraise)、瀏覽器設定和新分頁/視窗建立的任何引數都將被忽略。網頁將始終在使用者偏好的瀏覽器中的新分頁中開啟，並將瀏覽器帶到前台。在 iOS 上使用webbrowser 模組需要ctypes 模組。如果ctypes 不可用，則呼叫open() 將會失敗。

腳本webbrowser 可以用作模組的命令列介面。它接受 URL 作為引數。它接受以下可選參數：

-n,--new-window

如果可能的話會在新的瀏覽器視窗中開啟 URL。

-t,--new-tab

會在新的瀏覽器分頁 ("tab") 中開啟 URL。

這些選項自然是相互排斥的。用法範例如下：

python-mwebbrowser-t"https://www.python.org"

適用: not WASI, not Android.

以下例外有被定義於該模組：

exceptionwebbrowser.Error

當瀏覽器控制項發生錯誤時引發例外。

以下函式有被定義於該模組：

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

使用預設瀏覽器顯示url。如果new 為 0，則盡可能在同一瀏覽器視窗中開啟url。如果new 為 1，則盡可能開啟一個新的瀏覽器視窗。如果new 為 2，則盡可能開啟一個新的瀏覽器分頁 ("tab")。如果autoraise 為True，則盡可能提升視窗（請注意，無論此變數的設定如何，許多視窗管理器下都會發生這種情況）。

如果瀏覽器成功啟動則回傳True，否則回傳False。

請注意，在某些平台上，嘗試使用此函式開啟檔案名稱可能能夠運作並啟動作業系統的關聯程式。然而這既不支援也不可移植。

引發一個附帶引數url 的稽核事件webbrowser.open。

webbrowser.open_new(url)

盡可能在預設瀏覽器的新視窗中開啟url，否則在唯一的瀏覽器視窗中開啟url。

如果瀏覽器成功啟動則回傳True，否則回傳False。

webbrowser.open_new_tab(url)

盡可能在預設瀏覽器的新分頁 ("tab") 中開啟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() 函式的類型名稱以及控制器類別的相應實例化方式，這些都定義於此模組中。

類型名稱

類別名稱

註解

'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 上。

在 3.2 版被加入:新增了MacOSXOSAScript 類別並於 Mac 上使用，而非使用先前的MacOSX 類別。這增加了對開啟目前未設定為作業系統預設之瀏覽器的支援。

在 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)

瀏覽器控制器物件

瀏覽器控制器提供了name 屬性和以下三個與模組層級便利函式相同的方法：

controller.name

瀏覽器的系統相依名稱 (system-dependent name)。

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

使用此控制器處理的瀏覽器顯示url。如果new 為 1，則盡可能開啟一個新的瀏覽器視窗。如果new 為 2，則盡可能開啟一個新的瀏覽器分頁 ("tab")。

controller.open_new(url)

盡可能在此控制器處理的瀏覽器的新視窗中開啟url，否則在唯一的瀏覽器視窗中開啟url。別名為open_new()。

controller.open_new_tab(url)

盡可能在此控制器處理的瀏覽器的新分頁 ("tab") 中開啟url，否則相當於open_new()。

註腳

[1]

此處命名的無完整路徑可執行檔將在PATH 環境變數中給定的目錄中被搜尋。