"webbrowser" --- 方便的 Web 浏览器控制工具
******************************************

**源码：** Lib/webbrowser.py

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

"webbrowser" 模块提供了一个高层级接口，允许向用户显示基于 Web 的文档。
在大多数情况下，只需调用此模块中的 "open()" 函数即可。

在 Unix 下，图形浏览器在 X11 下是首选，但如果图形浏览器不可用或 X11 显
示不可用，则将使用文本模式浏览器。 如果使用文本模式浏览器，则调用进程
将阻塞，直到用户退出浏览器。

如果存在环境变量 "BROWSER"，则将其解读为以 "os.pathsep" 分隔的浏览器列
表用于在平台默认值之前进行尝试。 当列表部分的值包含字符串 "%s" 时，则
会将其解读为将以参数 URL 替换 "%s" 的浏览器命令行字面值；如果该值是指
向某个已注册的浏览器的单独单词则该浏览器会被添加到搜索列表的开头；如果
该部分不包含 "%s"，则会被简单解读为要启动的浏览器的名称。 [1]

在 3.14 版本发生变更: 现在 "BROWSER" 变量还可被用来对平台默认值进行重
新排序。 这在 macOS 上特别有用因其平台默认值不是指向 "PATH" 中的命令行
工具。

对于非 Unix 平台，或者当 Unix 上有远程浏览器时，控制过程不会等待用户完
成浏览器，而是允许远程浏览器在显示界面上维护自己的窗口。 如果 Unix 上
没有远程浏览器，控制进程将启动一个新的浏览器并等待。

在 iOS 上，"BROWSER" 环境变量以及任何控制 autoraise、浏览器偏好和新建
标签页/窗口的参数都将被忽略。 网页将 *始终* 在用户首选的浏览器中以新标
签页打开，并将浏览器置于前台。 在 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"。

   请注意，在某些平台上，尝试使用此函数打开文件名，可能会起作用并启动
   操作系统的关联程序。 但是，这种方式不被支持也不可移植。

   引发一个 审计事件 "webbrowser.open" 并附带参数 "url"。

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()" 函数的类型名称以
及控制器类的相应实例化，这些都在此模块中定义。

+--------------------------+-------------------------------------------+---------+
| 类型名                   | 类名                                      | 备注    |
|==========================|===========================================|=========|
| "'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: 在 Mac 上会使用新增的 "MacOSXOSAScript" 类而不是
之前的 "MacOSX" 类。 它增加了对打开当前未被设为 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)


浏览器控制器对象
================

浏览器控制器提供了 "name" 属性，和以下三个与模块级便捷函数相对应的方法
：

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()"。

-[ 脚注 ]-

[1] 这里命名的不带完整路径的可执行文件将在 "PATH" 环境变量给出的目录中
    搜索。
