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

**原始碼：**Lib/webbrowser.py

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

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

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

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

在 3.14 版的變更: The "BROWSER" variable can now also be used to
reorder the list of platform defaults. This is particularly useful on
macOS where the platform defaults do not refer to command-line tools
on "PATH".

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

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


命令列介面
==========

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

-n, --new-window

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

-t, --new-tab

   會在新的瀏覽器分頁 ("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，則盡可能開啟一個新的瀏覽器分頁 ("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" 環境變數中給定的目錄中被搜
    尋。
