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

原始碼：Lib/webbrowser.py

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

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

如果存在环境变量 BROWSER ，则将其解释为 os.pathsep 分隔的浏览器列表，以便在平台默认值之前尝试。 当列表部分的值包含字符串 ％s 时，它被解释为一个文字浏览器命令行，用于替换 ％s 的参数 URL ；如果该部分不包含 ％s，则它只被解释为要启动的浏览器的名称。 [1]

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

脚本 webbrowser 可以用作模块的命令行界面。它接受一个 URL 作为参数。还接受以下可选参数：-n 如果可能，在新的浏览器窗口中打开 URL ； -t 在新的浏览器页面（“标签”）中打开 URL。这些选择当然是相互排斥的。用法示例:

python -m webbrowser -t "https://www.python.org"

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssembly 平台 for more information.

定义了以下异常：

exception webbrowser.Error

发生浏览器控件错误时引发异常。

定义了以下函数：

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

使用默认浏览器显示 url。 如果 new 为 0，则尽可能在同一浏览器窗口中打开 url。 如果 new 为 1，则尽可能打开新的浏览器窗口。 如果 new 为 2，则尽可能打开新的浏览器页面（“标签”）。 如果 autoraise 为 “True”，则会尽可能置前窗口（请注意，在许多窗口管理器下，无论此变量的设置如何，都会置前窗口）。

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

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

webbrowser.open_new(url)

如果可能，在默认浏览器的新窗口中打开 url，否则，在唯一的浏览器窗口中打开 url。

webbrowser.open_new_tab(url)

如果可能，在默认浏览器的新页面（“标签”）中打开 url，否则等效于 open_new()。

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

'netscape'

Mozilla('netscape')

'galeon'

Galeon('galeon')

'epiphany'

Galeon('epiphany')

'skipstone'

BackgroundBrowser('skipstone')

'kfmclient'

Konqueror()

(1)

'konqueror'

Konqueror()

(1)

'kfm'

Konqueror()

(1)

'mosaic'

BackgroundBrowser('mosaic')

'opera'

Opera()

'grail'

Grail()

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

註解：

  1. “Konqueror” 是 Unix 的 KDE 桌面环境的文件管理器，只有在 KDE 运行时才有意义。 一些可靠地检测 KDE 的方法会很好；仅检查 KDEDIR 变量是不够的。 另请注意，KDE 2的 konqueror 命令，会使用名称 “kfm”---此实现选择运行的 Konqueror 的最佳策略。

  2. 仅限 Windows 平台。

  3. 仅限 macOS 平台。

在 3.3 版新加入: 添加了对 Chrome/Chromium 的支持。

自從版本 3.11 後不推薦使用，將會自版本 3.13 中移除。: MacOSX is deprecated, use MacOSXOSAScript instead.

以下是一些簡單範例：

url = 'https://docs.python.org/'

# Open URL in a new tab, if a browser window is already open.
webbrowser.open_new_tab(url)

# Open URL in new window, raising the window if possible.
webbrowser.open_new(url)

浏览器控制器对象

浏览器控制器提供三个与模块级便捷函数相同的方法：

webbrowser.name

System-dependent name for the browser.

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

註解